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1. Introduction 


This document describes the syntax, semantics and use of the COBOL programming lan- 
guage as implemented by GnuCOBOL, formerly known as OpenCOBOL. 


The original principal developers of GnuCOBOL were Keisuke Nishida and Roger While. 
Since then, many members of the community have been involved in its development. 


This document is intended to serve as a fully functional reference and light user’s guide, 
suitable for both those readers learning COBOL for the first time as a light training tool, 
as well as those already familiar with another dialect of COBOL. 


A separate manual — containing only the basic details of the GnuCOBOL implementa- 
tion and designed for experienced COBOL programmers — has been taken from this guide. 
That document (GnuCOBOL Quick Reference) contains no training subject matter. 


A new manual that is based on this manual (Programmers Guide) is the Programmers 
Reference. This will have any training material removed so it will be a detailed Reference 
only. There are a few issues to overcome in that it uses currently the same text for the 
Guide and this will need changing in some areas in order to remove any training materials 
creating new text documents used as input to build this manual. 


Other documents that should be read is the gnucobol.pdf found in the doc directory 
of the compiler sources and the file NEWS supplied with the source code of the GnuCOBOL 
compiler, in the top-level directory. There you will find the latest COBOL language features 
that have been added, some of which may not be in this document due to time constraints. 
If you find any, please report it as a bug for the Programmer’s Guide so that it can be fixed. 


Yet another document which delves deeper in to the compiler that is a must read, 
is the FAQ available via the GnuCOBOL Manuals and Guides (https: //gnucobol . 
sourceforge .io/#faq), although it could do with a wee clean up to ease reading and 
finding required information. 


1.1. Additional Reference Sources 


For those wishing to learn COBOL for the first time, Gary can strongly recommend the 
following resources. 


If you like to hold a book in your hands, I strongly recommend Murach’s Structured 
COBOL, by Mike Murach, Anne Prince and Raul Menendez (2000) - ISBN 9781890774059. 
Mike Murach and his various writing partners have been writing outstanding COBOL text- 
books for decades. It’s an excellent book for those familiar with the concepts of programming 
in other languages, but unfamiliar with COBOL. 

Another to consider is COBOL Unleashed by Jon Wessler, et al (with many other con- 
tributors) dated 1998 - ISBN 9780672312540 - 1,000 pages, which is perhaps more geared 
to the mainframe but with much related to other platform including for GnuCOBOL which 
Vincent finds very useful at times. 

One more is Beginning COBOL for Programmers Paperback 20 Mar. 2014 by Michael 
Coughlan - ISBN 978-1430262534 which may well be worth a read. There are many others. 

Would you prefer a web-based tutorial? Try the University of Limerick (Ireland) - 
COBOL web site (http: //www.csis.ul.ie/cobol/). 
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In addition there is the GnuCOBOL FAQ (https: //gnucobol. sourceforge. io/faq/ 
index.html) — which has now exceeded 1,400 pages — available as HTML or a download- 
able .pdf file. 


Along with every release of the compiler sources is the file NEWS. It contains up to the 
minute updates regarding the compiler and additional COBOL language elements which 
may well not be yet included in this manual. 


1.2. Introducing COBOL 


If you already know a programming language other than COBOL, chances are that lan- 
guage is Java, C or C++. You will find COBOL much different from those; sometimes the 
differences are a good thing and sometimes they aren’t. The thing to remember about 
COBOL is this: it was designed to solve business problems. 


COBOL, first introduced to the programming public in 1959, was the very first program- 
ming language to become standardized (in 1960). This meant that a standard-compliant 
COBOL program written on computer “A” made by company “B” would be able to be 
compiled and executed on computer “X” made by company “Y” with very few, if any, 
changes. This may not seem like such a big deal today, but it was a radical departure from 
all programming languages that came before it and even many that came after it. 


The name COBOL actually says it all — COBOL is an acronym that stands for 
“(CO)mmon (B)usiness (O)riented (L)anguage”. Note the fact that the word “common” 


comes before all others. The word “business” is a close second. Therein lies the key to 
COBOL’s success. 


1.2.1. Why YOU Should Learn COBOL 


Despite statements from industry “insiders”, the COBOL programming language is not 
dead, even though newer and so-called “modern” languages like Java, C#, .NET, Ruby on 
Rails and so on appear to have become the languages of choice in the Information Technology 
world. These languages have become popular because they address the following desired 
requirements for “modern” programming: 


1. They conform to the principles of Object-Oriented Programming (OOP). This is desired 
for one major reason — it facilitates “code re-usability” , thus improving the productiv- 
ity of programmers by allowing them to re-use previously written (and debugged) code 
in new applications. For one reason or another, COBOL is perceived as being weak in 
this regard. It isn’t (especially today), as we’ll see in the next section, but perception 
is important. 


2. Those languages aren’t limited to mainframe computers, as COBOL is perceived to be. 
Some, like .NET and Ruby, aren’t even available on mainframes. The “modern” pro- 
gramming languages were designed and intended for use on the full variety of computer 
platforms, from shirt-pocket computers (i.e. smart phones) up to the most massive of 
supercomputers. 


3. There are several excellent commercially available COBOL implementations available 
for non-mainframe systems (Micro Focus Visual COBOL, AccuCOBOL, NetCOBOL 
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and Elastic COBOL, just to name a few), including Windows and UNIX/Linux systems. 
These aren’t cheap, however. 


4, Universities love the “Modern” languages. In the U.S., 73% of colleges lack even one 
COBOL course on their curricula. COBOL, it appears, is no longer “cool” enough for 
students to fill a classroom. 


Just because COBOL doesn’t traditionally support objects, classes, and the like doesn’t 
mean that its “procedural” approach to computing isn’t valuable — after all, it runs 70% 
of the worlds business transactions, and does so utilising over 200 billion lines of code 
(according to research): 


e Using programs that, for the most part, are much more self-documenting than would 
be the case with any other programming language. 


e Effortlessly providing arithmetic accuracy to 31 digits, with performance approaching 
that of well-written assembly-language programs. Don’t think this isn’t critically im- 
portant to banks, investment houses and any business interested in tracking revenues, 
expenses and profits (duh - like ALL of them). 


e Integrating well with non-COBOL infrastructures such as XML, SOA, MQ, almost 
any DBMS, Transaction Processing platforms, Queue-Management facilities and other 
programming languages. 

e Byrunning on almost as many different computing platforms as Java can. You can’t run 
COBOL programs in your smart phone, but desktops, workstations, midframes/servers, 
mainframes and supercomputers are all fair game. 


Today’s IT managers and business leaders are faced with a challenging dilemma — how do 
you maintain the enormous COBOL code base that is still running their businesses when 
academia has all but abandoned the language they need their people to use to keep the 
wheels rolling? The problem is compounded by the fact that those programmers that are 
skilled in COBOL are retiring and taking their knowledge with them. In some markets, this 
appears to be having an inflationary effect on the cost of resources (COBOL programmers) 
whose supply is becoming smaller and smaller. The pressure to update applications to make 
use of more up-to-date graphical user interfaces is also perceived as a reason to abandon 
COBOL in favour of GUI-friendly languages such as Java. 


Businesses are addressing the COBOL challenge in different ways: 


1. By undertaking so-called “modernization projects”, where existing applications are 
either rewritten in “modern” languages or replaced outright with purchased pack- 
ages. Most of these businesses are using such activities as an excuse to abandon 
“expensive” mainframes in favour of (presumably) less-expensive “open systems” (mid 
frame/server) solutions. 


2. Many times these businesses are finding the cost of the system/networking engineering, 
operational management and monitoring and risk management (i.e. disaster recovery) 
infrastructures necessary to support truly mission-critical applications to be so high 
that the “less-expensive” solution really isn’t; in these cases the mainframe may remain 
the best option, thus leaving COBOL in play and businesses seeking another solution 
for at least part of their application base. 
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3. Training their own COBOL programmers. Since colleges, universities and technical 
schools have lost interest in doing so, many businesses have undertaken the task of 
“erowing their own” new crop of COBOL programmers. Fear of being pigeon-holed into 
a niche technology is a factor inhibiting many of today’s programmers from willingly 
volunteering for such training. 


4. By moving the user-interface onto the desktop; such efforts involve running modern- 
language front-end clients on user desktops (or laptops or smart phones, etc.) with 
COBOL programs providing server functionality on mainframe or midframe platforms, 
providing all the database and file “heavy lifting” on the back-end. Solutions like this 
provide users with the user-interfaces they want/need while still leveraging COBOL’s 
strengths on (possibly) downsized legacy mainframe or midframe systems. 


It’s probably a true that an IT professional can no longer afford to allow COBOL to be 
the only wrench in their toolbox, but with a massive code base still in production now and 
for the foreseeable future, adding COBOL to a multi-lingual curriculum vitae (CV) and/or 
resume (yes — they ARE different) is not a bad thing at all. Knowing COBOL as well as 
the language du-jour will make you the smartest person in the room when the discussion of 
migrating the current “legacy” environment to a “modern” implementation comes around. 


You'll find COBOL an easy language to learn and a FAR EASIER language to master 
than many of the “modern” languages. 


The whole reason you’re reading this is that you’ve discovered GnuCOBOL — another 
implementation of COBOL in addition to those mentioned earlier. The distinguishing char- 
acteristic of GnuCOBOL versus those others is that GnuCOBOL is FREE open-source and 
therefore FREE to obtain and use. It is community-enhanced and community-supported. 
Later in this document (see [So What is GnuCOBOL?], page 8), you’ll begin to learn more 
about this COBOL implementation’s capabilities. 


1.2.2. Programmer Productivity 


Throughout the history of computer programming, the search for new ways to improve of 
the productivity of programmers has been a major consideration. Other than hobbyists, 
programming is an activity performed for money, and businesses abhor spending anything 
more than is absolutely necessary; even government agencies try to spend as little money 
on projects as is absolutely necessary. 


The amount of programming necessary to accomplish a given task — including rework 
needed by any errors found during testing (testing is sometimes jokingly defined as: that 
time during which an application is actually in production, allowing users to discover the 
problems) is the measure of programmer productivity. Anything that reduces that effort will 
therefore reduce the time spent in such activities therefore reducing the expense of same. 
When the expense of programming is reduced, programmer productivity is increased. 


Sometimes the quest for improved programmer productivity (and therefore reduced pro- 
gramming expense) has taken the form of introducing new features in programming lan- 
guages, or even new languages altogether. Sometimes it has resulted in new ways of using 
the existing languages. 
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While many technological and procedural developments have made evolutionary im- 
provements to programmer productivity, each of the following three events has been re- 
sponsible for revolutionary improvements: 


e The development of so-called “higher-level” programming languages that enable a pro- 
grammer to specify in a single statement of the language an action that would have 
required many more separate statements in a prior programming language. The stan- 
dardization of such languages, making them usable on a wide variety of computers and 
operating systems, was a key aspect of this development. COBOL was a pioneering de- 
velopment in this area, being a direct descendant of the very first higher-level language 
(FLOW-MATIC, developed by US Naval Lieutenant Grace Hopper) and the first to 
become standardized. 


e The establishment of programming techniques that make programs easier to read and 
therefore easier to understand. Not only do such techniques reduce the amount of 
rework necessary simply to make a program work as designed, but they also reduce the 
amount of time a programmer needs to study an existing program in order how to best 
adapt it to changing business requirements. The foremost development in this area was 
structured programming. Introduced in the late 1970’s, this approach to programming 
spawned new programming languages (PASCAL, ALGOL, PL/1 and so forth) designed 
around it. With the ANSI 85 standard, COBOL embraced the principles espoused 
by structured programming mavens as well as any of the languages designed strictly 
around it. 


e The establishment of programming techniques AND the introduction of programming 
language capabilities to facilitate the re-usability of program code. Anything that sup- 
ports code re-usability can have a profound impact to the amount of time it takes to 
develop new applications or to make significant changes to existing ones. In recent 
years, object-oriented programming (OOP) has been the industry “poster child” for 
code re-usability. By enabling program logic and the data structures that logic manip- 
ulates to be encapsulated into easily stored and retrieved (and therefore “reusable” ) 
modules called classes, the object-oriented languages such as Java, C++ and C# have 
become the favourites of academia. Since students are being trained in these languages 
and only these, by and large, it’s no surprise that — today — object-oriented program- 
ming languages are the darlings of the industry. 


The reality is, however, that good programmers have been practising code re-usability 
for more than a half-century. Up until recently, COBOL programmers have had some 
of the best code re-usability tools available — they’ve been doing it with copybooks 
and subprograms rather than classes, methods and attributes but the net results have 
been similar. With the COBOL2002 and the COBOL 2014 standards, the COBOL pro- 
gramming language has become just as “object-oriented” as the “modern” languages, 
while preserving the ability to support, modify, compile and execute “legacy” COBOL 
programs as well. 


While GnuCOBOL supports few of the OOP programming constructs defined by the 
COBOL2002 and COBOL2014 standards, it supports every aspect of the ANSI 85 
standard and therefore fully meets the needs of points #1 and #2, above. With its 
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supported feature set (see [So What is GnuCOBOL’], page 8), it provides significant 
programmer productivity capabilities. 


1.3. So What is GnuCOBOL? 


GnuCOBOL is a free and open sourced COBOL compiler and runtime environment, written 
using the C programming language which itself is free to use and can be used in all forms 
including for commercial purposes - there is no restrictions. GnuCOBOL is typically dis- 
tributed in source-code form, and must then be built for your computer’s operating system 
using the system’s C compiler and loader. While originally developed for the UNIX and 
Linux operating systems, GnuCOBOL has also been successfully built for computers running 
OSX (a OpenBSD implementation) and Windows utilizing the UNIX-emulation features of 
such tools as Cygwin and MinGW. Also see the GNU website (https: //savannah. gnu. 
org/projects/gnucobol) for more information. Pre built Implemeations for Windows can 
also be found at https: //www.arnoldtrembley.com/GnuCOBOL. htm. 


The MinGW approach is a personal favourite with the author of this manual because it 
creates a GnuCOBOL compiler and runtime library that require only a single MinGW DLL 
to be available for the GnuCOBOL compiler, runtime library and user programs. That 
DLL is freely distributable under the terms of the GNU General Public License. A MinGW 
build of GnuCOBOL fits easily on and runs from a 128MB flash drive with no need to 
install any software onto the Windows computer that will be using it. Some functionality of 
the language, dealing with the sharing of files between concurrently executing GnuCOBOL 
programs and record locking on certain types of files, is sacrificed however as the underlying 
operating system routines needed to implement them aren’t available to Windows and aren’t 
provided by MinGW. The current version for MinGW is available at the download link along 
with various other platforms at the GnuCOBOL https://sourceforge.net/projects/ 
gnucobol/files/gnu-cobol, download website. 


GnuCOBOL has also been built as a truly native Windows application utilizing Mi- 
crosoft’s freely-downloadable Visual Studio Community package to provide the C compiler 
and linker/loader. This approach does not lend itself well to a “portable” distribution. 


The GnuCOBOL compiler generates C code from your COBOL source programs; that C 
code is then automatically compiled and linked using your system’s C compiler (typically, 
but not limited to, gcc). 

GnuCOBOL fully supports much of the ANSI 85 standard for COBOL (the only major 
exclusion is the Communications Module) and also supports some of the components of 
the COBOL2002 and COBOL2014 standards, such as the SCREEN SECTION (see [SCREEN 
SECTION], page 143), table-based SORT (see [Table SORT], page 395) and user-defined 
functions. There are others with more being added almost weekly. 


End of Chapter 1 — Introduction 
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2. COBOL Fundamentals 


This chapter describes the syntax, semantics and usage of the COBOL programming lan- 
guage as implemented by the current version of GnuCOBOL. For the rest of this document 
the Language is spelt as COBOL to ease reading however the compiler name retains the 
mixed case of GnuCOBOL. 


This document is intended to serve as a full-function reference and user’s guide suitable 
for both those readers learning COBOL for the first time as usage as a training tool, as well 
as those already familiar with some dialects of the COBOL language. 


A separate manual exists that just contains the details of the Cobol grammar as imple- 
mented in GnuCOBOL, which is designed strictly for experienced COBOL programmers 
and this is taken from this guide. This does NOT contain any training subject matter what 
so ever. 


These extra manuals are: GnuCOBOL Quick Reference containing just the COBOL 
semantics / grammar in a short document while the other, GauCOBOL Sample Programs, 
shows detailed example Cobol programs with indication of syntax used in each program. 


For each implementation of the GnuCOBOL compiler the supplied files NEWS should 
also be read for any last minute updates along with files README and INSTALL for 
building the compiler. 


2.1. The COBOL Language - The Basics 


2.1.1. Language Reserved Words 


Cobol programs consist of a sequence of words and symbols. Words, which consist of 
sequences of letters (upper- and/or lower-case), digits, dashes (‘-’) and/or underscores 
(‘_’) may have a pre-defined, specific, meaning to the compiler or may be invented by 
the programmer for his/her purposes. 


The GnuCOBOL language specification defines well over 1130 Reserved Words — words 
to which the compiler assigns a special meaning. This list and number applies to the default 
list which covers many implementations. It is possible to limit the list to either a specific 
implementation via -std=xyz|-strict] or to manually unreserve words if they are used in 
existing sources as user-defined words. 


Programmers may use a reserved word as part of a word they are creating themselves, 
but may not create their own word as an exact duplicate (without regard to case) of a 
COBOL reserved word. Note that a reserved word includes all classes, such as intrinsic 
functions, mnemonics names, system routines. The list of reserved words can be changed 
by adding or removing specific words for a given compile or as a default by use of the 
steering command -std= (dialect) and —conf= (users config file). See the specific config files 
that are by default, held in /usr/local/share/gnucobol/config. Also using the option 
‘FUNCTION ALL INTRINSIC’, will add another 100+ reserved words. These can be modified 
to match the requirements of a business or project team but be Warned, that these are 
updated when a new version of the compiler is built so might be more prudent to create 
your own configuation based on an existing one but with a different name. 
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In addition, you can add and/or remove reserved words by adding one of these op- 
tions to cobc to add -freserved=word or, to remove, -fnot-reserved=word. As well as 
-freserved=word: alias to create an alias for a word as well as -fnot-register=word or 
-fregister=word to remove or add, a special register word. 


See Appendix’s B for a complete list of GnuCOBOL reserved words and Cl - 4 (for 
grouped word lists). 


For any given version of GnuCOBOL you can also list the full current set of reserved 
words by running cobc with --list-reserved, --list-intrinsic, --list-system as well 
as --list-mnemonics. Again subject to variation depending on usage of the --std line 
command. 


2.1.2. User-Defined Words 


When you write GnuCOBOL programs, you'll need to create a variety of words to represent 
various aspects of the program, the program’s data and the external environment in which 
the program will run. This will include internal names by which data files will be referenced, 
data item names and names of executable logic procedures as section and paragraph names. 


User-defined words may be composed from the characters ‘A’ through ‘Z’ (upper- and/or 
lower-case), ‘0’ through ‘9’, dash (‘-’) and underscore (‘_’). | User-defined words may 


neither start nor end with hyphen or underscore characters. 


Other programming languages provide the programmer with a similar capability of cre- 
ating their own words (names) for parts of a program; COBOL is somewhat unusual when 
compared to other languages in that user-defined words may start with a digit. 


With the exception of logic procedure names, which may consist entirely of nothing but 
digits, user-defined words must contain at least one letter. 


The maximum size of a user defined word in Cobol is 31 characters as per the COBOL 
2014 Standard but to help support other compilers it can be extended by the usage of -std 
(COBOL85 and ibm-strict has 30) to increase the limit to 63 characters. It must be pointed 
out that exceeding the standard limit will seriously restrict the ability of transferring any 
code written for GnuCOBOL to another brand of compiler without changing all such user 
defined words to 30 or 31. The whole art of writing using Cobol is to minimise the need to 
change any code over the years that your programs will be in use. 


There are very many examples of programs written going back to the 1960’s that are 
still in operation around the world and the number of lines of Cobol code is estimated at 
200 billion. 


For example, this author (Vincent Coen) has code going back to the early 60’s with 
admittedly changes over the years, still in full operation, just take a look at the Contrib 
area and check out cobxref - Cobol Cross Reference listing tool (also on Sourceforge), 
dectrans - (Decision Translator), flightlog - Pilots Log Book (also on Sourceforge), and also 
in Sourceforge - ACAS (Applewood Computers Accounting System) - this one with the 
original code only, going back to 1967. 


Of course many if not most of these applications have had many changes, upgrades etc, 
over the years, but it shows just how long programs written in Cobol have survived and 
gone on in full time use for some 60 years. 
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The point is that, when writing in Cobol, you should always consider is, will the code be 
transferrable to another system or compiler in the years to come, but without going over 
the top ! 


2.1.3. Case Insensitivity 


All COBOL implementations allow the use of both upper and lower case letters in program 
coding. GnuCOBOL is completely insensitive to the case used when writing reserved words 
or user-defined names. Thus, AAAAA, aaaaa, Aaaaa and AaAaA are all the same word as far 
as GnuCOBOL is concerned. 


The only time the case used does matter is within quoted character strings, where 
character values will be exactly as coded. 


By convention throughout this document, COBOL reserved words will be shown entirely 
in UPPER-CASE while those words that were created by a programmer will be represented 
by tokens in mixed or lower case. 


This isn’t a bad practice to use in actual programs, as it leads to programs where it is 
much easier to distinguish reserved words from user-defined ones! 


2.1.4. Readability of Programs 


Critics of COBOL frequently focus on the wordiness of the language, often citing the case 
of a so-called “Hello World” program as the “proof” that COBOL is so much more tedious 
to program in than more “modern” languages. This tedium is cited as such a significant 
impact to programmer productivity that, in their opinions, COBOL can’t go away quickly 
enough. 


Here are two different “Hello World” applications, one written in Java and the second 
in GnuCOBOL. First, the Java version: 


Class HelloWorld { 
public static void main(String[] args) { 
System.out.println("Hello World!"); 
} 
} 


And here is the same program, written in GnuCOBOL: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. HelloWorld. 
PROCEDURE DIVISION. 

DISPLAY "Hello World!". 


Both of the above programs could have been written on a single line, if desired, and both 
languages allow a programmer to use (or not use) indentation as they see fit to improve 
program readability. Sounds like a tie so far. 


Let’s look at how much more “wordy” COBOL is than Java. Count the characters in the 
two programs. The Java program has 95 (not counting carriage returns and any indenta- 
tion). The COBOL program has 89 (again, not counting carriage returns and indentation)! 
Technically, it could have been only 65 because the IDENTIFICATION DIVISION. header is 
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actually optional. Clearly, “Hello World” doesn’t look any more concise in Java than it 
does in COBOL. 


Let’s look at a different problem. Surely a program that asks a user to input a positive 
integer, generates the sum of all positive integers from 1 to that number and then prints 
the result will be MUCH shorter and MUCH easier to understand when coded in Java than 
in COBOL, right? 


You can be the judge. First, the Java version: 


import java.util.Scanner; 
public class sumofintegers { 
public static void main(String[] arg) { 
System.out.println("Enter a positive integer") ; 
Scanner scan=new Scanner (System.in) ; 
int n=scan.nextInt(); 
int sum=0; 
for (int i=1;i<=n;i++) { 
sumt+=i ; 
F 


System.out.println("The sum is "+sum) ; 


} 
And now for the COBOL version: 


IDENTIFICATION DIVISION. 

PROGRAM-ID. SumOfIntegers. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 n  BINARY-LONG. 

01 i BINARY-LONG. 

01 sum BINARY-LONG VALUE 0. 

PROCEDURE DIVISION. 

DISPLAY "Enter a positive integer" 

ACCEPT n 

PERFORM VARYING i FROM 1 BY 1 UNTIL ion 
ADD i TO sum 

END-PERFORM 

DISPLAY "The sum is " sum. 


My familiarity with COBOL may be prejudicing my opinion, but it doesn’t appear to 
me that the Java code is any simpler than the COBOL code. In case you’re interested in 
character counts, the Java code comes in at 278 (not counting indentation characters). The 
COBOL code is 298 (274 without the IDENTIFICATION DIVISION. header). 


Despite what you’ve seen here, the more complex the programming logic being imple- 
mented, the more concise the Java code will appear to be, even compared to 2002-standard 
COBOL. That conciseness comes with a price though — program code readability. Java (or 
C or C++ or C#) programs are generally intelligible only to trained programmers. COBOL 
programs can, however, be quite understandable by non-programmers. This is actually a 
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side-effect of the “wordiness” of the language, where COBOL statements use natural En- 
glish words to describe their actions. This inherent readability has come in handy many 
times throughout my career when I’ve had to learn obscure business (or legal) processes by 
reading the COBOL program code that supports them. 


The “modern” languages, like Java, also have their own “boilerplate” infrastructure over- 
head that must be coded in order to write the logic that is necessary in the program. Take for 
example the public static void main(String[] arg) and import java.util.Scanner; 
statements. The critics tend to forget about this when they criticize COBOL for its struc- 
tural “overhead”. 


When it first was developed, COBOL’s easily-readable syntax made it profoundly differ- 
ent from anything that had been seen before. For the first time, it was possible to specify 
logic in a manner that was — at least to some extent — comprehensible even to non- 
programmers. Take for example, the following code written in FORTRAN — a language 
developed only a year before COBOL: 


EXT = PRICE * IQTY 
INVTOT = INVTOT + EXT 


With its original limitation on the length of variable names (one- to six-character names 
comprised of a letter followed by up to five letters and/or digits), its implicit rule that 
variables were automatically created as real (floating-point) unless their name started with 
a letter in the range I-N, and its use of algebraic notation to express actions being taken, 
FORTRAN wasn’t a particularly readable language, even for programmers. Compare this 
with the equivalent COBOL code: 


MULTIPLY price BY quantity GIVING extended-amount 
ADD extended-amount TO invoice-total 


Clearly, even a non-programmer could at least conceptually understand what was go- 
ing on! Over time, languages like FORTRAN evolved more robust variable names, and 
COBOL introduced a more formula-based syntactical capability for arithmetic operations, 
but FORTRAN was never as readable as COBOL. 


Because of its inherent readability, I would MUCH rather be handed an assignment to 
make significant changes to a COBOL program about which I know nothing than to be 
asked to do the same with a C, C++, C# or Java program. 


Those that argue that it is too boring / wasteful / time-consuming / insulting (pick one) 
to have to code a COBOL program “from scratch” are clearly ignorant of the following 
facts: 


e Many systems have program-development tools available to ease the task of coding 
programs; those tools that concentrate on COBOL are capable of providing templates 
for much of the “overhead” verbiage of any program... 

e Good programmers have — for decades — maintained their own skeleton “template” 
programs for a variety of program types; simply load a template into a text editor and 
you've got a good start to the program... 

e Legend has it that there’s actually only been ONE program ever written in COBOL, and 
all programs ever “written” thereafter were simply derivatives of that one. Although 
this is clearly intended as a (probably) bad joke, it is nevertheless close to the very 
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simple truth that many programmers “reuse” existing COBOL programs when creating 
new ones. There’s certainly nothing preventing this from happening with programs 
written in other languages, but it does seem to happen more in COBOL shops. It’s 
ironic that “code re-usability” is one of the arguments used to justify the existence of 
the “modern” languages. 


2.1.5. Divisions Organize Programs 


COBOL programs are structured into four major areas of coding, each with its own purpose. 
These four areas are known as divisions. 


Each division may consist of a variety of sections and each section consists of one or 
more paragraphs. A paragraph consists of sentences, each of which consists of one or more 
statements. 


This hierarchical structure of program components standardises the composition of all 
COBOL programs. Much of this manual describes the various divisions, sections, para- 
graphs and statements that may comprise any COBOL program. 


2.1.6. Copybooks 


COPY statement (see [COPY], page 63) A Copybook is a segment of program code that may 
be utilized by multiple programs simply by having those programs use the COPY statement 
to import that code. This code may define files, data structures or procedural code. 


Today’s current programming languages have a statement (usually, this statement is 
named “import”, “include” or “#include”) that performs this same function. What makes 
the COBOL copybook feature different than the “include” facility in newer languages, 
however, is the fact that the COPY statement can edit the imported source code as it is 
being copied. This capability makes copybook libraries extremely valuable to making code 
reusable. Also see section 3. Compiler Directing Facility commands COPY and REPLACE. 


2.1.7. Structured Data 


A contiguous area of storage within the memory space of a program that may be referenced, 
by name, in a COBOL program is referred to asa Data Item. Other programming languages 
use the term variable, property or attribute to describe the same thing. 


COBOL introduced the concept of structured data. The principle of structured data 
in COBOL is based on the idea of being able to group related and contiguously-allocated 
data items together into a single aggregate data item, called a Group Item. For example, 
a 35-character "Employee-Name’ group item might consist of a 20-character *Last-Name’ 
followed by a 14-character ’First-Name’ and a 1-character ’Middle-Initial’. 


A data item that isn’t itself formed from other data items is referred to in COBOL as an 
Elementary Item. In the previous example, ’Last-Name’, ’First-Name’ and ’Middle-Initial’ 
are all elementary items. 


2.1.8. Files 


One of COBOL’s strengths is the wide variety of data files it is capable of accessing. Gnu- 
COBOL programs, like those created with other COBOL implementations, need to have the 
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structure of any files they will be reading and/or writing described to them. The highest- 
level characteristic of a file’s structure is defined by specifying the organization of the file, 
as follows: 


ORGANIZATION LINE SEQUENTIAL 

These are files with the simplest of all internal structures. Their contents are 
structured simply as a series of identically- or differently-sized data records, 
each terminated by a special end-of-record delimiter character. An ASCII line- 
feed character (hexadecimal 0A) is the end-of-record delimiter character used 
by any UNIX or pseudo-UNIX (MinGW, Cygwin, OSX) GnuCOBOL build. A 
truly native Windows build would use a carriage-return, line-feed (hexadecimal 
ODOA) sequence. 


Records must be read from or written to these files in a purely sequential 
manner. The only way to read (or write) record number 100 would be to have 
read (or written) records number 1 through 99 first. 


When the file is written to by a GnuCOBOL program, the delimiter sequence 
will be automatically appended to each data record as it is written to the file. 
A WRITE (see [WRITE], page 417) to this type of file will be done as if a BEFORE 
ADVANCING 1 LINE clause were specified on the WRITE, if no ADVANCING clause 
is coded. 


When the file is read, the GnuCOBOL runtime system will strip the trailing 
delimiter sequence from each record. The data will be padded (on the right) 
with spaces if the data just read is shorter than the area described for data 
records in the program. If the data is too long, it will be truncated and the 
excess will be lost. 


These files should not be defined to contain any exact binary data fields because 
the contents of those fields could inadvertently have the end-of-record sequence 
as part of their values — this would confuse the runtime system when reading 
the file, and it would interpret that value as an actual end-of-record sequence. 


The following environment variables can have an effect on LINE SEQUENTIAL 
processing behaviour so may require changes to settings for: 


COB_LS_FIXED 
COB_LS_NULLS 
COB_LS_SPLIT 


When using Micro Focus compatable formats: 
COB-MF-LS-NULLS 

COB_MF_LS_INSTAB 

COB_MF_LS_SPLIT 

COB_MF_LS_VALIDATE 


See sections 10.2.3.4 and 10.2.3.7 for more information. 


LINE ADVANCING 
These are files with an internal structure similar to that of a line sequential 
file. These files are defined (without an explicit ORGANIZATION specification) 
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using the LINE ADVANCING clause on their SELECT statement (see [SELECT], 
page 104). 

When this kind of file is written to by a GnuCOBOL program, an end-of- 
record delimiter sequence will be automatically added to each data record as it 
is written to the file. A WRITE to this type of file will be done as if an AFTER 
ADVANCING 1 LINE clause were specified on the WRITE, if no ADVANCING clause 
is coded. 


Like line sequential files, these files should not be defined to contain any exact 
binary data fields because the contents of those fields could inadvertently have 
the end-of-record sequence as part of their values — this would confuse the 
runtime system when reading the file, and it would interpret that value as an 
actual end-of-record sequence. 


ORGANIZATION SEQUENTIAL 

These files also have a simple internal structure. Their contents are structured 
simply as an arbitrarily-long sequence of data characters. This sequence of 
characters will be treated as a series of fixed-length records simply by logically 
splitting the sequence of characters up into fixed-length segments, each as long 
as the maximum record size defined in the program. There are no special end- 
of-record delimiter characters in the file and when the file is written to by a 
GnuCOBOL program, no delimiter sequence is appended to the data. 


Records in this type of file are all the same physical length, except possibly 
for the very last record in the file, which may be shorter than the others. If 
variable-length logical records are defined to the program, the space occupied 
by each physical record in the file will occupy the space described by the longest 
record description in the program. 


So, if a file contains 1275 characters of data, and a program defines the struc- 
ture of that file as containing 100-character records, then the file contents will 
consist of twelve (12) 100-character records with a final record containing only 
75 characters. 


It would appear that it should be possible to locate and process any record in 
the file directly simply by calculating its starting character position based upon 
the program-defined record size. Even so, however, records must be still be 
read or written to these files in a purely sequential manner. The only way to 
read (or write) record number 100 would be to have read (or written) records 
number 1 through 99 first. 


When the file is read, the data is transferred into the program exactly as it 
exists in the file. In the event that a short record is read as the very last record, 
that record will be padded (to the right) with spaces. 


Care must be taken that programs reading such a file describe records whose 
length is exactly the same as that used by the program that created the file. 
For example, the following shows the contents of a SEQUENTIAL file created by 
a program that wrote five 6-character records to it. The ‘A’, ‘B’, ... values 
reflect the records that were written to the file: 

‘AAAAAN’ 
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‘BBBBBB’ 
‘CCCCCC’ 
‘DDDDDD’ 
‘EEEEEE’ 


Now, assume that another program reads this file, but describes 10-character 
records rather than 6. Here are the records that program will read: 
‘AAAAAABBBB’ 
‘BBCCCCCCDD’ 
‘DDDDEEEEEE’ 


There may be times where this is exactly what you were looking for. More often 
than not, however, this is not desirable behaviour. Suggestion: use a copybook 
to describe the record layouts of any file; this guarantees that multiple programs 
accessing that file will “see” the same record sizes and layouts by coding a COPY 
statement (see [COPY], page 63) to import the record layout(s) rather than 
hand-coding them. 


These files can contain exact binary data fields. Because there is no character 
sequence that constitutes an end-of-record delimiter, the contents of record 
fields are irrelevant to the reading process. 


ORGANIZATION RELATIVE 
The contents of these files consist of a series of fixed-length data records prefixed 
with a four-byte record header. The record header contains the length of the 
data, in bytes. The byte-count does not include the four-byte record header. 


Records in this type of file are all the same physical length. If variable-length 
logical records are defined to the program, the space occupied by each physical 
record in the file will occupy the maximum possible space, and the logical 
record length field will contain the number of bytes of data in the record that 
are actually in use. 


This file organization was defined to accommodate either sequential or ran- 
dom processing. With a RELATIVE file, it is possible to read or write record 
100 directly, without having to have first read or written records 1-99. The 
GnuCOBOL runtime system uses the program-defined maximum record size to 
calculate a relative byte position in the file where the record header and data 
begin, and then transfers the necessary data to or from the program. 


When the file is written by a GnuCOBOL program, no delimiter sequence is 
appended to the data, but a record-length field is added to the beginning of 
each physical record. 


When the file is read, the data is transferred into the program exactly as it 
exists in the file. 


Care must be taken that programs reading such a file describe records whose 
length is exactly the same as that used by the programs that created the file. It 
won’t end well if the GnuCOBOL runtime library interprets a four-byte ASCII 
character string as a record length when it transfers data from the file into the 
program! 
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Suggestion: use a copybook to describe the record layouts of any file; this 
guarantees that multiple programs accessing that file will “see” the same record 
sizes and layouts by coding a COPY statement (see [COPY], page 63) to import 
the record layout(s) rather than hand-coding them. 


These files can contain exact binary data fields. The contents of record fields 
are irrelevant to the reading process as there is no end-of-record delimiter. 


ORGANIZATION INDEXED 
This is the most advanced file structure available to GnuCOBOL programs. 
It’s not possible to describe the physical structure of such files because that 
structure will vary depending upon which advanced file-management facility 
was included into the GnuCOBOL build you will be using (Berkeley Database 
[BDB], VBISAM, etc.). We will — instead — discuss the logical structure of 
the file. 


There will be multiple structures stored for an INDEXED file. The first will be 
a data component, which may be thought of as being similar to the internal 
structure of a relative file. Data records may not, however, be directly accessed 
by their record number as would be the case with a relative file, nor may they 
be processed sequentially by their physical sequence in the file. 


The remaining structures will be one or more index components. An index 
component is a data structure that (somehow) enables the contents of a field, 
called a primary key, within each data record (a customer number, an employee 
number, a product code, a name, etc.) to be converted to a record number 
so that the data record for any given primary key value can be directly read, 
written and/or deleted. Additionally, the index data structure is defined in such 
a manner as to allow the file to be processed sequentially, record-by-record, in 
ascending sequence of the primary key field values. Whether this index structure 
exists as a binary-searchable tree structure (b-tree), an elaborate hash structure 
or something else is pretty much irrelevant to the programmer — the behaviour 
of the structure will be as it was just described. The actual mechanism used 
will depend upon the advanced file-management package was included into your 
GnuCOBOL implementation when it was built. 


The runtime system will not allow two records to be written to an indexed file 
with the same primary key value. 


The capability exists for an additional field to be defined as what is known as 
an alternate key. Alternate key fields behave just like primary keys, allowing 
both direct and sequential access to record data based upon the alternate key 
field values, with one exception. That exception is the fact that alternate keys 
may be allowed to have duplicate values, depending upon how the alternate key 
field is described to the GnuCOBOL compiler. 


There may be any number of alternate keys, but each key field comes with 
a disk space penalty as well as an execution time penalty. As the number of 
alternate key fields increases, it will take longer and longer to write and/or 
modify records in the file. 
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These files can contain exact binary data fields. The contents of record fields 
are irrelevant to the reading process as there is no end-of-record delimiter. 


All files are initially described to a GnuCOBOL program using a SELECT statement (see 
[SELECT], page 104). In addition to defining a name by which the file will be referenced 
within the program, the SELECT statement will specify the name and path by which the 
file will be known to the operating system along with its organization, locking and sharing 
attributes. 


A file description in the FILE SECTION (see [FILE SECTION], page 123) will define the 
structure of records within the file, including whether or not variable-length records are 
possible and, if so, what the minimum and maximum length might be. In addition, the file 
description entry can specify file I/O block sizes. 


2.1.9. Table Handling 


Other programming languages have arrays; COBOL has tables. They’re basically the same 
thing. There are two special statements that exist in the COBOL language — SEARCH and 
SEARCH ALL — that make finding data in a table easy. 


SEARCH searches a table sequentially, stopping only when either a table entry matching 
one of any number of search conditions is found, or when all table entries have been checked 
against the search criteria and none matched any of those criteria. 


SEARCH ALL performs an extremely fast search against a table sorted by a key field 
contained in each table entry. The algorithm used for such a search is a binary search. The 
algorithm ensures that only a small number of entries in the table need to be checked in 
order to find a desired entry or to determine that the desired entry doesn’t exist in the table. 
The larger the table, the more effective this search becomes. For example, a binary search 
of a table containing 32,768 entries will locate a particular entry or determine the entry 
doesn’t exist by looking at no more than fifteen (15) entries! The algorithm is explained in 
detail in the documentation of the SEARCH ALL statement (see [SEARCH ALL], page 379). 


Finally, COBOL has the ability to perform in-place sorts of the data that is found in a 
table. 


2.1.10. Sorting and Merging Data 


The COBOL language includes a powerful SORT statement that can sort large amounts of 
data according to arbitrarily complex key structures. This data may originate from within 
the program or may be contained in one or more external files. The sorted data may be 
written automatically to one or more output files or may be processed, record-by-record in 
the sorted sequence. 


A companion statement — MERGE — can combine the contents of multiple files together, 
provided those files are all pre-sorted in a similar manner according to the same key struc- 
ture. The resulting output will consist of the contents of all of the input files, merged 
together and sequenced according to the common key structure(s). The output generated 
by a MERGE statement may be written automatically to one or more output files or may be 
processed internally by the program. 
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A special form of the SORT statement also exists just to sort the data that resides in a 
table. This is particularly useful if you wish to use SEARCH ALL against the table. 


2.1.11. String Manipulation 


There have been programming languages designed specifically for the processing of text 
strings, and there have been programming languages designed for the sole purpose of per- 
forming high-powered numerical computations. Most programming languages fall some- 
where in the middle. 

COBOL is no exception, although it does include some very powerful string manipula- 
tion capabilities; GnuCOBOL actually has even more string-manipulation capabilities than 
many other COBOL implementations. The following summarizes GnuCOBOL’s string- 
processing capabilities: 


Concatenate two or more strings 
e CONCATENATE intrinsic function (see [CONCATENATE], page 433). 
e STRING statement (see [STRING], page 401). 


Conversion of a numeric time or date to a formatted character string 
e LOCALE-TIME intrinsic function (see [LOCALE-TIME], page 469). 


e LOCALE-DATE intrinsic function (see [LOCALE-DATE], page 468). 


Convert a binary value to its corresponding character in the program’s character set 
e CHAR intrinsic function (see [CHAR], page 430). Add 1 to argument before 
invoking the function; the description of the CHAR intrinsic function presents 
a technique utilizing the MOVE statement that will accomplish the same 
thing without the need of adding 1 to the numeric argument value first. 


Convert a character string to lower-case 
e LOWER-CASE intrinsic function (see [LOWER-CASE], page 473). 
e C$TOLOWER built-in system subroutine (see [CSTOLOWER], page 552). 
e CBL_TOLOWER built-in system subroutine (see [CBL-TOLOWER], 
page 592). 
Convert a character string to upper-case 
e UPPER-CASE intrinsic function (see [UPPER-CASE], page 525). 
e C$TOUPPER built-in system subroutine (see [CSTOUPPER], page 553). 
e CBL_TOUPPER built-in system subroutine (see [CBL-TOUPPER], 
page 592). 


Convert a character string to only printable characters 
e C$PRINTABLE built-in system subroutine (see [CSPRINTABLE], page 550). 


Convert a character to its numeric value in the program’s character set 
e ORD intrinsic function (see [ORD], page 497). Subtract 1 from the result; 
the description of the ORD intrinsic function presents a technique utilizing 
the MOVE statement that will accomplish the same thing without the need 
of adding 1 to the numeric argument value first. 


Chapter 2 - COBOL Fundamentals 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 21 


Count occurrences of sub strings in a larger string 
e INSPECT statement (see [INSPECT], page 344) with the TALLYING clause. 


Decode a formatted numeric string back to a numeric value 
e NUMVAL intrinsic function (see [NUMVAL], page 492). 


e NUMVAL-C intrinsic function (see [NUMVAL-C], page 493). 


Determine the length of a string or data-item capable of storing strings 
e LENGTH intrinsic function (see [LENGTH], page 465). 


e BYTE-LENGTH intrinsic function (see [BYTE-LENGTH], page 429). 


Extract a sub string from a string based on its starting character position and length 
e Use of a reference modifier on the string field - See [Reference Modifiers], 
page 40. 


Format a numeric item for output, including thousands-separators (‘,’ in the USA), 
currency symbols (‘$’ in the USA), decimal points, credit /Debit Symbols, Leading Or 
Trailing Sign Characters 
e MOVE statement (see [MOVE], page 352) with picture-symbol editing ap- 
plied to the receiving field: 


Justification (left, right or centred) of a string field 
e C$JUSTIFY built-in system subroutine (see [CSJUSTIFY], page 546). 


Monoalphabetic substitution of one or more characters in a string with different characters 
e INSPECT statement (see [INSPECT], page 344) with the CONVERTING. 
e TRANSFORM statement (see [TRANSFORM], page 411). 
e SUBSTITUTE intrinsic function (see [SUBSTITUTE], page 514). 
e SUBSTITUTE-CASE intrinsic function (see [SUBSTITUTE-CASE], 
page 515). 


Parse a string, breaking it up into sub strings based upon one or more delimiting 
character sequences! 
e UNSTRING statement (see [UNSTRING], page 413). 


Removal of leading or trailing spaces from a string 
e TRIM intrinsic function (see [TRIM], page 524). 


Substitution of a single sub string with another of the same length, based upon the sub 
strings starting character position and length 
e MOVE statement (see [MOVE], page 352) with a reference modifier on the 
“receiving” field (see [Reference Modifiers], page 40). 


Substitution of one or more sub strings in a string with replacement sub strings of the 
same length, regardless of where they occur 
e INSPECT statement (see [INSPECT], page 344) with a REPLACING clause. 


e SUBSTITUTE intrinsic function (see [SUBSTITUTE], page 514). 


! These delimiters may be single characters, multiple-character strings or multiple consecutive occurrences 
of either 
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e SUBSTITUTE-CASE intrinsic function (see [SUBSTITUTE-CASE], 
page 515). 


Substitution of one or more sub strings in a string with replacement sub strings of a 
potentially different length, regardless of where they occur 
e SUBSTITUTE intrinsic function (see [SUBSTITUTE], page 514). 


e SUBSTITUTE-CASE intrinsic function (see [SUBSTITUTE-CASE], 
page 515). 


2.1.12. Screen Formatting Features 


The COBOL2002 standard formalizes extensions to the COBOL language that allow for the 
definition and processing of text-based screens, as is a typical function on mainframe and 
midframe computers as well as on many point-of-sale (i.e. “cash register”) systems. Gnu- 
COBOL implements virtually all the screen-handling features described by COBOL2002. 


These features allow fields to be displayed at specific row/column positions, various colors 
and video attributes to be assigned to screen fields and the pressing of specific function keys 
(F1, F2, ...) to be detectable. All of this takes place through the auspices of the SCREEN 
SECTION (see [SCREEN SECTION], page 143) and special formats of the ACCEPT statement 
(see [ACCEPT], page 268) and the DISPLAY statement (see [DISPLAY], page 305). 


The COBOL2002 standard, and therefore GnuCOBOL, only covers textual user interface 
(TUT) screens (those comprised of ASCII characters presented using a variety of visual 
attributes) and not the more-advanced graphical user interface (GUI) screen design and 
processing capabilities built into most modern operating systems. There are subroutine- 
based packages available that can do full GUI presentation — most of which may be called 
by GnuCOBOL programs, with a moderate research time investment (Tcl/Tk, for example) 
— but none are currently included with GnuCOBOL. 
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2.1.12.1. A Sample Screen 

A Sample Screen Produced by a GnuCOBOL Program: 
F GNU COBOL Compile; I 
GCic (2013/12/26 10:16) GNU COBOL 2.1 23NOV2013 Interactive Compilation 


mathtest .cb] 
E:\Programs\Samples 


F1-F9 


DEFAULT 


GCic for Windows/MinGW Copyright (C) 2009-2013, Gary L. Cutler, GPL 


The above screen was produced by the GnuCOBOL Interactive Compiler, or GCic. See 
Section “GCic” in GnuCOBOL Sample Programs, for the source and cross-reference listing 
of this program. 


Screens are defined in the screen section of the data division. Once defined, screens are 
used at run-time via the ACCEPT and DISPLAY statements. 


2.1.12.2. Color Palette and Video Attributes 


GnuCOBOL supports the following visual attribute specifications in the SCREEN SECTION 
(see [SCREEN SECTION], page 143): 


Color Eight (8) different colors may be specified for both the background (screen) 
and foreground (text) color of any row/column position on the screen. Colors 
are specified by number, although a copybook supplied with all GnuCOBOL 
distributions (screenio.cpy) defines COB-COLOR-xxxxxx names for the vari- 
ous colors so they may be specified as a more meaningful name rather than 
a number. The eight colors, by number, with the constant names defined in 
screenio.cpy, are as follows: 


Black COB-COLOR-BLACK 
Blue COB-COLOR-BLUE 
Green COB-COLOR-GREEN 
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Cyan COB-COLOR-CYAN 

Red COB-COLOR-RED 
Magenta COB-COLOR-MAGENTA 
Yellow COB-COLOR- YELLOW 
White COB-COLOR-WHITE 


Text Brightness 
There are three possible brightness levels supported for text — lowlight (dim), 
normal and highlight (bright). Not all GnuCOBOL implementations will sup- 
port all three (some treat lowlight the same as normal). The deciding factor as 
to whether two or three levels are supported lies with the version of the curses 
package that is being used. This is a utility screen-IO package that is included 
into the GnuCOBOL run-time library when the GnuCOBOL software is built. 


As a general rule of thumb, Windows implementations support two levels while 
Unix ones support all three. 


Blinking This too is a video feature that is dependent upon the curses package built into 
your version of GnuCOBOL. If blinking is enabled in that package, text dis- 
played in fields defined in the screen section as being blinking will endlessly cy- 
cle between the brightest possible setting (highlight) and an “invisible” setting 
where the text color matches that of the field background color. A Windows 
build, which generally uses the “pcurses” package, will uses a brighter-than- 
normal background color to signify “blinking”. 


Reverse Video 
This video attribute simply swaps the foreground and background colors and 
display options. 


Field Outlining 
It is possible, if supported by the curses package being used, to draw borders 
on the top, left and/or bottom edges of a field. 


Secure Input 
If desired, screen fields used as input fields may defined as “secure” fields, where 
each input character (regardless of what was actually typed) will appear as an 
asterisk (*) character. The actual character whose key was pressed will still be 
stored into the field in the program, however. This is very useful for password 
or account number fields. 


Prompt Character 
Input fields may have any character used as a fill character. These fill characters 
provide a visual indication of the size of the input field, and will automatically 
be transformed into spaces when the input field is processed by the program. 
If no such character is defined for an input field, an underscore (‘_’) will be 
assumed. 


The following is a sample of the GnuCOBOL color Palette, showing all possible combi- 
nations of the various video attributes. This example was prepared on a Macintosh running 
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OSX Mavericks (10.9). Blinking works — the screen snapshot shows things in mid blink, 
when the text and background colors are momentarily the same. Unfortunately, only two 
screen intensities are available (like Windows, the “lowlight” setting is the same as the 
default). 


The GnuCOBOL Color Palette and Video Options:: 


(ish) 2013-11-23-2.1 — bash — 65x26 we 


(Press ENTER when done) 
LOWLIGHT HIGHLIGHT LOWLIGHT 


REVERSE 
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LOWLIGHT HIGHLIGHT LOWLIGHT HIGHLIGHT 
BLINK BLINK 
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SOvUEWNR © 
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The rows of each block are numbered with the background color while columns are 
numbered with the foreground color. 


See Section “Colors” in GnuCOBOL Sample Programs, for a source and cross-reference 
listing of the program (Colors.cbl) that produced the above screen. 


2.1.13. Report Writer Features 


GnuCOBOL includes an implementation of the Report Writer Control System, or RWCS. 
The reportwriter module is now fully implemented as of version 3.0. This is a standardized, 
optional add-on feature to the COBOL language which automates much of the mechanics 
involved in the generation of printed reports by: 
1. Controlling the pagination of reports, including: 
A. The automatic production of a one-time notice on the first page of the report 
(report heading). 


B. The production of zero or more header lines at the top of every page of the report 
(page heading). 
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C. The production of zero or more footer lines at the bottom of every page of the 
report (page footing). 

D. The automatic numbering of printed pages. 

E. The formatting of those report lines that make up the main body of the report 
(detail). 

F. Full awareness of where the “pen” is about to “write” on the current page, auto- 
matically forcing an eject to a new page, along with the automatic generation of 
a page footer to close the old page and/or a page header to begin the new one. 


G. The production of a one-time notice at the end of the last page of a report (report 
footing). 
2. Performing special reporting actions based upon the fact that the data being used to 
generate the report has been sorted according to one or more key fields: 


A. Automatically suppressing the presentation of one or more fields of data from 
the detail group when the value(s) of the field(s) duplicate those of the previously 
generated detail group. Fields such as these are referred to as group-indicate fields. 


B. Automatically causing suppressed detail group-indicate fields to re-appear should 
a detail group be printed on a new page. 


C. Recognizing when control fields on the report — fields tied to those that were used 
as SORT statement (see [SORT], page 391) keys — have changed. This is known 
as a control break. The RWCS can automatically perform the following reporting 
actions when a control break occurs: 


e Producing a footer, known as a control footing after the detail lines that shared 
the same old value for the control field. 


e Producing a header, known as a control heading before the detail lines that 
share the same new value for the control field. 


3. Perform data summarise, as follows: 


A. Automatically generating subtotals in control and/or report footings, summarizing 
values of any fields in the detail group. 

B. Automatically generating crossfoot totals in detail groups. These would be sums 
of two or more values presented in the detail group. 


The REPORT SECTION (see [REPORT SECTION], page 135) documentation explores 
the description of reports and the PROCEDURE DIVISION (see [PROCEDURE DIVISION], 
page 247) chapter documents the various language statements that actually produce reports. 
Before reading these, you might find it helpful to read [Report Writer Usage], page 601, 
which is dedicated to putting the pieces together for you. 


2.1.14. Data Initialization 


There are three ways in which data division data gets initialized. 


1. When a program or subprogram is first executed, much of the data in its data division 
will be initialized as follows: 


e Alphanumeric and alphabetic (i.e. text) data items will be initialized to SPACES. 


e Numeric data items will be initialized to a value of ZERO. 
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e Data items with an explicit VALUE (see [VALUE], page 244) clause in their defini- 
tion will be initialized to that specific value. 


The various sections of the data division each have their own rules as to when the 
actions described above will occur — consult the documentation on those sections for 
additional information. 


These default initialization rules can vary quite substantially from one COBOL imple- 
mentation to another. For example, it is quite common for data division storage to 
be initialized to all binary zeros except for those data items where VALUE clauses are 
present. Take care when working with applications originally developed for another 
COBOL implementation to ensure that GnuCOBOL’s default initialization rules won’t 
prove disruptive. 


2. A programmer may use the INITIALIZE statement (see [INITIALIZE], page 339) to 
initialise any group or elementary data item at any time. This statement provides far 
more initialization options than just the simple rules stated above. 


3. When the ALLOCATE statement (see [ALLOCATE], page 290) statement is used to 
allocate a data item or to simply allocate an area of storage of a size specified on 
the ALLOCATE, that allocation may occur with or without initialization, as per the 
programmer’s needs. 


2.1.15. Syntax Diagram Conventions 


Syntax of the GnuCOBOL language will be described in special syntax diagrams using the 
following syntactical-description techniques: 


MANDATORY-RESERVED-WORD 
Reserved words of the COBOL language will appear in UPPER-CASE. When 
they appear underlined, as this one is, they are required reserved words. 


OPTIONAL-RESERVED-WORD 
When reserved words appear without underlining, as this one is, they are op- 
tional; such reserved words are available in the language syntax merely to im- 
prove readability — their presence or absence has no effect upon the program. 


ABBREVIATION 

eo When only a portion of a reserved word is underlined, it indicates that the word 
may either be coded in its full form or may be abbreviated to the portion that 
is underlined. 


substitutable-items 
Generic terms representing user-defined substitutable items will be shown en- 
tirely in lower-case in syntax diagrams. When such items are referenced in text, 
they will appear as substitutable-items. 


Complex-Syntax-Clause 
Items appearing in Mixed Case within a syntax diagram represent complex 
clauses of other syntax elements that may appear in that position. Some 
COBOL syntax gets quite complicated, and using a convention such as this 
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significantly reduces the complexity of a syntax diagram. When such items are 
referenced in text, they will appear as Complex-Syntax-Clause. 


Bal Square bracket meta characters on syntax diagrams document language syntax 
that is optional. The |] characters themselves should not be coded. If a syntax 
diagram contains ‘a [b] c’, the ‘a’ and ‘c’ syntax elements are mandatory but 
the ‘b’ element is optional. 


Vertical bar meta characters on syntax diagrams document simple choices. The 
| character itself should not be coded. If a syntax diagram contains ‘alb|c’, 
exactly one of the items ‘a’, ‘b’ or ‘c’ must be selected. 


{ xxxxxx } 

t yyyyyy } 

{ zzzzzz } 
A vertical list of items, bounded by multiple brace characters, is another way 
of signifying a choice between a series of items where exactly one item must be 
selected. This form is used to show choices when one or more of the selections 
is more complex than just a single word, or when there are too many choices 
to present horizontally with ‘|’ meta characters. 

| xxxxxx | 

| yyyyyy | 

| zzzzzz | 
A vertical list of items, bounded by multiple vertical bar characters, signifies 
a choice between a series of items where one or more of the choices could be 
selected. 
The ... meta character sequence signifies that the syntax element immediately 
preceding it may be repeated. The ... sequence itself should not be coded. 
If a syntax diagram contains ab... c, syntax element ‘a’ must be followed 
by at least one ‘b’ element (possibly more) and the entire sequence must be 
terminated by a ‘c’ syntax element. 

{ } The braces (‘{’ and ‘}’) meta characters may be used to group a sequence of 


syntax elements together so that they may be treated as a single entity. The 
{} characters themselves should not be coded. These are typically used in 
combination with the ‘|’ or ‘...’ meta characters. 
$e" Qa i Sy > / 

Any of these characters appearing within a syntax diagram are to be interpreted 
literally, and are characters that must be coded — where allowed — in the 
statement whose format is being described. Note that a‘.’ character is a literal 
character that must be coded on a statement whereas a ‘...’ symbol is the 
meta character sequence described above. 


2.1.16. Format of Program Source Lines 


Prior to the COBOL2002 standard, source statements in COBOL programs were structured 
around 80-column punched cards. This means that each source line in a COBOL program 
consisted of five different “areas”, defined by their column number(s). 
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As of the COBOL2002 standard, a second mode now exists for COBOL source code 
statements — in this mode of operation, COBOL statements may each be up to 255 char- 
acters long, with no specific requirements as to what should appear in which columns. 


Of course, in keeping with the long-standing COBOL tradition of maintaining backwards 
compatibility with older standards, programmers (and, of course, compliant COBOL com- 
pilers) are capable of working in either mode. It is even possible to switch back and forth 
in the same program. The terms Fixed Format Mode and Free Format Mode are used 
to refer to these two modes of source code formatting. 


The GnuCOBOL compiler (cobc) supports both of these source line format modes, 
defaulting to Fixed Format Mode lacking any other information. 


The compiler can be instructed to operate in either mode in any of the following four 
ways: 
1. Using a compiler option switch — use the -fixed switch to start in Fixed Format 
Mode (remember that this is the default) or the -free switch to start in Free Format 
Mode. 


2. You may use the SOURCEFORMAT AS FIXED and SOURCEFORMAT AS FREE clauses of the 
>>SET CDF directive (see [>>SET], page 71) within your source code to switch to Fixed 
or Free Format Mode, respectively. 


3. You may use the >>FORMAT IS FIXED and FORMAT IS FREE clauses of the >>DEFINE 
CDF directive (see [>>DEFINE], page 68) within your source code to switch to Fixed 
or Free Format Mode, respectively. 


4. You may use the >>SOURCE CDF directive (see [>>SOURCE], page 73) to switch to Free 
Format Mode (>>SOURCE FORMAT IS FREE) or Fixed Format Mode (>>SOURCE FORMAT 
IS FIXED. 


Using methods 2-4 above, you may switch back and forth between the two formats at 
will. 


The last three options above are all equivalent; all three are supported by GnuCOBOL 
so that source code compatibility may be maintained with a wide variety of other COBOL 
implementations. With all three, if the compiler is currently in Fixed Format Mode, the >> 
must begin in column 8 or beyond, provided no part of the directive extends past column 
72. If the compiler is currently in Free Format Mode, the >> may appear in any column, 
provided no part of the directive extends past column 255. 


Depending upon which source format mode the compiler is in, you will need to follow 
various rules for the format mode currently in effect. These rules are presented in the 
upcoming paragraphs. 

The following discussion presents the various components of every GnuCOBOL source 
line record when the compiler is operating in Fixed Format Mode. Remember that this is 
the default mode for the GnuCOBOL compiler. 


1-6 Sequence Number Area 


Historically, back in the days when punched-cards were used to submit COBOL 
program source to a COBOL compiler, this part of a COBOL statement was 
reserved for a six-digit sequence number. While the contents of this area are 
ignored by COBOL compilers, it existed so that a program actually punched 
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on 80-character cards could — if the card deck were dropped on the floor — 
be run through a card sorter machine and restored to its proper sequence. Of 
course, this isn’t necessary today; if truth be told, it hasn’t been necessary for 
a long time. 


See [Marking Changes in Programs], page 695, for discussion of a valuable use 
to which the sequence number area may be put today. 


Indicator Area 


Column 7 serves as an indicator in which one of five possible values will appear 
— space, D (or d), - (dash), / or *. The meanings of these characters are as 
follows: 


space No special meaning — this is the normal character that will appear 
in this area. 


D/d The line contains a valid GnuCOBOL statement that is normally 
treated as a comment unless the program is being compiled in de- 
bugging mode. 


The line is a comment. 


‘| The line is a comment that will also force a page eject in the com- 
pilation listing. While GnuCOBOL will honour such a line as a 
comment, it will not form-feed any generated listing. 


- The line is a continuation of the previous line. These are needed 
only when an alphanumeric literal (quoted character string), re- 
served word or user-defined word are being split across lines. 


Area A 


Language DIVISION, SECTION and paragraph section headers must begin in 
Area A, as must the level numbers 01, 77 in data description entries and the 
FD and SD file and SORT description headers. 


Area B 


All other COBOL programming language components are coded in these 
columns. 


Program Name Area 


This is another obsolete area of COBOL statements. This part of every state- 
ment also hails back to the day when programs were punched on cards; it was 
expected that the name of the program (or at least the first 8 characters of 
it) would be punched here so that — if a dropped COBOL source deck con- 
tained more than one program — that handy card sorter machine could be 
used to first separate the cards by program name and then sort them by se- 
quence number. Today’s COBOL compilers (including GnuCOBOL) simply 
ignore anything past column 72. 


See [Marking Changes in Programs], page 695, for discussion of a valuable use 
to which the program name area may be put today. 
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2.1.17. Program Structure 


Complete GnuCOBOL Program Syntax 
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name-1 [ Program-Options ] 


Compilation-Computer-Specification . ] 
Execution-Computer-Specification . ] 
Function-Specification... . ] 


Program-Configuration-Specification . ] 


General-File-Description... . ] 


File-Buffering-Specification... . ] 


Detailed-File-Description... . ] 
Permanent-Data-Definition... . ] 
Temporary-Data-Definition... . ] 
Subprogram-Argument-Description... . ] 
Report-Description... . ] 


Screen-Layout-Definition... . ] 


Ww 
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[ RETURNING identifier-1 ] 
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Event-Handler-Routine... . ] 
END DECLARATIVES. ] 


General-Program-Logic 


| co OO ome | 


Nested-Subprogram... ] 
END PROGRAM|FUNCTION name-1 ] 


Each program consists of up to four Divisions (major groupings of sections, paragraphs and 
descriptive or procedural coding that all relate to a common purpose), named Identification, 
Environment, Data and Procedure. 


1. Not all divisions are needed in every program, but they must be specified in the order 
shown when they are used. 


2. The following points pertain to the identification division 


The IDENTIFICATION DIVISION. header is always optional. 


3. The following points pertain to the environment division: 


If both optional sections of this division are coded, they must be coded in the 
sequence shown. 


Each of these sections consists of a series of specific paragraphs (SOURCE-COMPUTER 
and OBJECT-COMPUTER, for example). Each of these paragraphs serves a specific 
purpose. If no code is required for the purpose one of the paragraphs serves, the 
entire paragraph may be omitted. 


If none of the paragraphs within one of the sections are coded, the section header 
itself may be omitted. 


The paragraphs within each section may only be coded in that section, but may 
be coded in any order. 


If none of the sections within the environment division are coded, the ENVIRONMENT 
DIVISION. header itself may be omitted. 


4. The following points pertain to the data division: 


The data division consists of six optional sections — when used, those sections 
must be coded in the order shown in the syntax diagram. 


Each of these sections consists of code which serves a specific purpose. If no code is 
required for the purpose one of those sections serves, the entire section, including 
its header, may be omitted. 


If none of the sections within the data division are coded (a highly unlikely, but the- 
oretically possible circumstance), the DATA DIVISION. header itself may be omit- 
ted. 


5. The following points pertain to the procedure division: 
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e As with the other divisions, the procedure division may consist of sections and 
those sections may — in turn — consist of paragraphs. Unlike the other divisions, 
however, section and paragraph names are defined by the programmer, and there 
may not be any defined at all if the programmer so wishes. 


e Each Event-Handler-Routine will be a separate section devoted to trapping a par- 
ticular run-time event. If there are no such sections coded, the DECLARATIVES. 
and END DECLARATIVES. lines may be omitted. 


6. A single file of COBOL source code may contain: 
e A portion of a program; these files are known as copybooks 


e A single program. In this case, the END PROGRAM or END FUNCTION statement is 
optional. 


e Multiple programs, separated from one another by END PROGRAM or END FUNCTION 
statements. The final program in such a source code file need not have an END 
PROGRAM or END FUNCTION statement. 


7. Subprogram ‘B’ may be nested inside program ‘A’ by including program B’s source code 
at the end of program A’s procedure division without an intervening END PROGRAM A. 
or END FUNCTION A. statement. For now, that’s all that will be said about nesting. See 
[Independent vs Contained vs Nested Subprograms], page 675, for more information. 


8. Regardless of how many programs comprise a single GnuCOBOL source file, only a 
single output executable program will be generated from that source file when the file 
is compiled. 


2.1.18. Comments 


The following information describes how comments may be embedded into GnuCOBOL 
program source to provide documentation. 


Comment Type Source Mode — Description 


Blank Lines FIXED — Blank lines may be inserted as desired. 

FREE — Blank lines may be inserted as desired. 
Full-line FIXED — An entire source line will be treated as a comment 
comments (and will be ignored by the compiler) by coding an asterisk (‘*’) 


in column seven (7). 

FREE — An entire source line will be treated as a comment 
(and will be ignored by the compiler) by coding the sequence 
‘*>’, starting in any column, as the first non-blank characters 
on the line. 
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Full-line FIXED — An entire source line will be treated as a comment 
comments with by coding a slash (‘/’) in column seven (7). Many COBOL 
form-feed compilers will also issue a form-feed in the program listing so 


that the ‘/’ line is at the top of a new page. The GnuCOBOL 
compiler does not support this form-feed behaviour. 

The GnuCOBOL Interactive Compiler, or GCic, does support 
this form-feed behaviour when it generates program source list- 
ings! See Section “GCic” in GnuCOBOL Sample Programs, 
for the source and cross-reference listing (produced by GCic) of 
this program — you can see the effect of ‘/’ there. 

FREE — There is no Free Source Mode equivalent to ‘/’. 

Partial-line FIXED — Any text following the character sequence ‘*>’ on a 
comments source line will be treated as a comment. The ‘*’ must appear 
in column seven (7) or beyond. 

FREE — Any text following the character sequence ‘*>’ on a 
source line will be treated as a comment. The ‘*’ may appear 
in any column. 

Comments that FIXED — By coding a ‘D’ in column 7 (upper- or lower-case), 

may be treated an otherwise valid GnuCOBOL source line will be treated as a 

as code, typi- comment by the compiler. 

cally for debug- | FREE — By specifying the character sequence ‘>>D’ (upper- 

ging purposes or lower-case) as the first non-blank characters on a source line, 
an otherwise valid GnuCOBOL source line will be treated as a 
comment by the compiler. 

Debugging statements may be compiled either by specify- 
ing the -fdebugging-line switch on the GnuCOBOL com- 
piler or by adding the WITH DEBUGGING MODE clause to the 
SOURCE-COMPUTER paragraph. 


2.1.19. Literals 


Literals are constant values that will not change during the execution of a program. There 
are two fundamental types of literals — numeric and alphanumeric. 


2.1.19.1. Numeric Literals 


A numeric literal 


e Integers such as 1, 56, 2192 or -54. 
e Non-integer fixed point values such as 1.317 or -2.95. 


e Floating-point values using ‘Enn’ notation such as 9.92E25, representing 9.92 x 10”° 
(10 raised to the 25th power) or 5.7E-14, representing 5.7 x 10~'* (10 raised to the 
-14th power). Both the mantissa (the number before the ‘E’) and the exponent (the 
number after the ‘E’) may be explicitly specified as positive (with a ‘+’), negative (with 
a ‘-’) or unsigned (and therefore implicitly positive). A floating-point literals value 
must be within the range —1.7 x 10°° to +1.7 x 10°°° with no more than 15 decimal 


digits of precision. 
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e Hexadecimal numeric literals 

e Null terminated literals 

e Raw C string using L"characters". 

e Binary using B#0 or 1. 

e Octal using O#0 - 7. (That is the letter ‘0’). 

e Hexadecimal number using H# or X# ‘0’ - ‘F’. 

e Boolean Literals (Standard) B" character ". 

e Boolean Literals (Hexadecimal) BX" hex character ". 

e National Literals (Standard) N" character " or NC" character ". 


e National Literals (Hexadecimal) NX" character ". 


2.1.19.2. Alphanumeric Literals 
An alphanumeric literal 


An alphanumeric literal is not valid for use in arithmetic expressions unless it is first 
converted to its numeric computational equivalent; there are three numeric conversion 
intrinsic functions built into GnuCOBOL that can perform this conversion — NUMVAL 
(see [NUMVAL], page 492), NUMVAL-C (see [NUMVAL-C], page 493) and NUMVAL-F (see 
[NUMVAL-F], page 496). 


Alphanumeric literals may take any of the following forms: 
e A sequence of characters enclosed by a pair of single-quote (‘’’) 


e A literal formed according to the same rules as for a string literal (above), but prefixed 
with the letter ‘Z’ (upper- or lower-case) constitutes a zero-delimited string literal. 
These literals differ from ordinary string literals in that they will be explicitly ter- 
minated with a byte of hexadecimal value 00. These Zero-Delimited Alphanumeric 
Literals 


e A Hexadecimal Alphanumeric Literal 


Alphanumeric literals too long to fit on a single line may be continued to the next line 
in one of two ways: 


1. If you are using Fixed Format Mode, the alphanumeric literal can be run right up to 
and including column 72. The literal may then be continued on the next line anywhere 
after column 11 by coding another quote or apostrophe (whichever was used to begin 
the literal originally). The continuation line must also have a hyphen (-) 


1 2 3 4 5 6 7 
1234567890123456789012345678901234567890123456789012345678901234567890123 


01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a long 1 
- "ong literal that 
= "must be continu 
- "ed.". 

2. Regardless of whether the compiler is operating in Fixed or Free Format Mode, Gnu- 
COBOL allows alphanumeric literals to be broken up into separate fragments. These 
fragments have their own beginning and ending quote/apostrophe characters and are 
“olued together” at compilation time using ‘&’ 
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1 2 3 4 5 6 7 
1234567890123456789012345678901234567890123456789012345678901234567890123 


01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a" & 
"long literal that must " & 
"be continued.". 
If your program is using Free Format Mode, there’s less need to continue long alphanu- 
meric literals because statements may be as long as 255 characters. 


Numeric literals may be split across lines just as alphanumeric literals are, using either of 
the above techniques and both reserved and user-defined words can be split across lines too 
(using the first technique). The continuation of numeric literals and user-defined/reserved 
words is provided merely to provide compatibility with older COBOL versions and pro- 
grams, but should not be used with new programs — it just makes for ugly-looking pro- 
grams. 


2.1.19.3. Figurative Constants 


Figurative constants are reserved words that may be used as literals anywhere the figurative 
constants value could be interpreted as an arbitrarily long sequence of the characters in 
question. When a specific length is required, such as would be the case with an argument 
to a subprogram, a figurative constant may not be used. Thus, the following are valid uses 
of figurative constants: 


05 FILLER PIC 9(10) VALUE ZEROS. 


MOVE SPACES TO Employee-Name 
But this is not: 


CALL "SUBPGM" USING SPACES 


The following are the GnuCOBOL figurative constants and their respective equivalent 
values. 


ZERO This figurative constant has a value of numeric 0 (zero). ZEROS and ZEROES are 
both synonyms of ZERO. 


SPACE This figurative constant has a value of one or more space characters. SPACES is 
a synonym of SPACE. 


QUOTE This figurative constant has a value of one or more double-quote characters ("). 
QUOTES is a synonym of QUOTE. 


LOW-VALUE 
This figurative constant has a value of one or more of whatever character oc- 
cupies the lowest position in the program’s collating sequence as defined in the 
OBJECT-COMPUTER (see [OBJECT-COMPUTER], page 90) paragraph or — if 
no such specification was made — in whatever default character set the program 
is using (typically, this is the ASCII character set). LOW-VALUES is a synonym 
of LOW-VALUE. 
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When the character set in use is ASCII with no collating sequence modifications, 
the LOW-VALUES figurative constant value is the ASCII NUL character. Because 
character sets can be redefined, however, you should not rely on this fact. Use 
the NULL figurative constant instead. 


HIGH-VALUE 
This figurative constant has a value of one or more of whatever character oc- 
cupies the highest position in the program’s collating sequence as defined in 
the OBJECT-COMPUTER paragraph or — if no such specification was made — in 
whatever default character set the program is using (typically, this is the ASCII 
character set). HIGH-VALUES is a synonym of HIGH-VALUE. 


NULL A character comprised entirely of zero-bits (regardless of the programs collating 
sequence). 


Programmers may create their own figurative constants via the SYMBOLIC CHARACTERS 
(see [Symbolic-Characters-Clause], page 100) clause of the SPECIAL-NAMES (see [SPECIAL- 
NAMES], page 92) paragraph. 


2.1.20. Punctuation 
A comma (‘,’) 

The use of comma characters can cause confusion to a COBOL compiler if the DECIMAL 
POINT IS COMMA clause is used in the SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) 
paragraph, as might be the case in Europe. The following statement, which calls a subrou- 


tine passing it two arguments (the numeric constants 1 and 2): 
CALL "SUBROUTINE" USING 1,2 


Would — with DECIMAL POINT IS COMMA in effect — actually be interpreted as a subrou- 
tine call with 1 argument (the non-integer numeric literal whose value is 1 and 2 tenths). 
For this reason, it is best to always follow a comma with a space. 


The period character (‘.’) 


The rules for where and when periods are needed in the procedure division are somewhat 
complicated. See [Use of Periods], page 54, for the details. 


2.1.21. Interfacing to Other Environments 


Through the CALL statement, COBOL programs may invoke other COBOL programs serv- 
ing as subprograms. This is quite similar to cross-program linkage capabilities provided 
by other languages. In GnuCOBOL’s case, the CALL facility is powerful enough to be tai- 
lored to the point where a GnuCOBOL program can communicate with operating system, 
database management and run-time library APIs, even if they weren’t written in COBOL 
themselves. See [GnuCOBOL Main Programs CALLing C Subprograms], page 690, for an 
example of how a GnuCOBOL program could invoke a C-language subprogram, passing 
information back and forth between the two. 


The fact that GnuCOBOL supports a full-featured two-way interface with C-language 
programs means that — even if you cannot access a library API directly — you could always 
do so via a small C “wrapper” program that is CALLed by a GnuCOBOL program. 
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2.2. The COBOL Language - Advanced Techniques 


2.2.1. Table References 


COBOL uses parenthesis to specify the subscripts used to reference table entries (tables in 
COBOL are what other programming languages refer to as arrays). 
For example, observe the following data structure which defines a 4 column by 3 row 
grid of characters: 
O1 GRID. 
05 GRID-ROW OCCURS 3 TIMES. 
10 GRID-COLUMN OCCURS 4 TIMES. 


15 GRID-CHARACTER PIC X(1). 

If the structure contains the following grid of characters: 
ABCD 
EFGH 
IJKL 


Then GRID-CHARACTER (2, 3) references the ‘G’ and GRID-CHARACTER (3, 2) references 
the ‘J’. 

Subscripts may be specified as numeric (integer) literals, numeric (integer) data items, 
data items created with any of the picture-less integer USAGE (see [USAGE], page 232) 
specifications, USAGE INDEX data items or arithmetic expressions resulting in a non-zero 
integer value. 


In the above examples, a comma is used as a separator character between the two sub- 
script values; semicolons (;) are also valid subscript separator characters, as are spaces! 
The use of a comma or semicolon separator in such a situation is technically optional, but 
by convention most COBOL programmers use one or the other. The use of no separator 
character (other than a space) is not recommended, even though it is syntactically correct, 
as this practice can lead to programmer-unfriendly code. It isn’t too difficult to read and un- 
derstand GRID-CHARACTER (2 3), but it’s another story entirely when trying to comprehend 
GRID-CHARACTER(I + 1 J / 3) (instead of GRID-CHARACTER(I +1, J / 3)). The compiler 
accepts it, but too much of this would make my head hurt. 


Chapter 2 - COBOL Fundamentals 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 39 


2.2.2. Qualification of Data Names 


COBOL allows data names to be duplicated within a program, provided references to those 
data names may be made in such a manner as to make those references unique through a 
process known as qualification. 


To see qualification at work, observe the following segments of two data records defined 
in a COBOL program: 


01 EMPLOYEE. 01 CUSTOMER. 
05 MAILING-ADDRESS. 05 MAILING-ADDRESS. 
10 STREET PIC X(35). 10 STREET PIC X(35). 
10 CITY PIC X(15). 10 CITY PIC X(15). 
10 STATE PIC X(2). 10 STATE PIC X(2). 
10 ZIP-CODE. 10 ZIP-CODE. 
15 ZIP-CODE-5 PIC 9(5). 15 ZIP-CODE-5 PIC 9(5). 
15 FILLER PIC X(4). 15 FILLER PIC X(4). 


Now, let’s deal with the problem of setting the CITY portion of an EMPLOYEEs 
MAILING-ADDRESS to ‘Philadelphia’. Clearly, MOVE ’Philadelphia’ TO CITY cannot 
work because the compiler will be unable to determine which of the two CITY fields you 
are referring to. 


In an attempt to correct the problem, we could qualify the reference to CITY as MOVE 
>Philadelphia’ TO CITY OF MAILING-ADDRESS. 

Unfortunately that too is insufficient because it still insufficiently specifies which CITY is 
being referenced. To truly identify which specific CITY you want, you’d have to code MOVE 
*>Philadelphia’ TO CITY OF MAILING-ADDRESS OF EMPLOYEE. 


Now there can be no confusion as to which CITY is being changed. Fortunately, you don’t 
need to be quite so specific; COBOL allows intermediate and unnecessary qualification levels 
to be omitted. This allows MOVE ’Philadelphia’ TO CITY OF EMPLOYEE to do the job nicely. 


If you need to qualify a reference to a table, do so by coding something like identifier-1 
OF identifier-2 ( subscript(s) ). 


The reserved word IN may be used in lieu of OF. 
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2.2.3. Reference Modifiers 


Reference Modifier (Format 1) Syntax ] 


identifier-1 [ OF|IN identifier-2 ] [ (subscript...) ] (start:[ length ]) 


Reference Modifier (Format 2) Syntax | 


intrinsic-function-reference (start:[ length ]) 


The COBOL 1985 standard introduced the concept of a reference modifier to facilitate ref- 
erences to only a portion of a data item; GnuCOBOL fully supports reference modification. 


The start value indicates the starting character position being referenced (character 
position values start with 1, not 0 as is the case in some programming languages) and 
length specifies how many characters are wanted. 


If no length is specified, a value equivalent to the remaining character positions from 


start to the end of identifier-1 or to the end of the value returned by the function will be 
assumed. 


Both start and length may be specified as integer numeric literals, integer numeric data 
items or arithmetic expressions with an integer value. 


Here are a few examples: 


CUSTOMER-LAST-NAME (1:3) 
References the first three characters of CUSTOMER-LAST-NAME. 


CUSTOMER-LAST-NAME (4:) 
References all character positions of CUSTOMER-LAST-NAME from the fourth on- 
ward. 


FUNCTION CURRENT-DATE (5:2) 
References the current month as a 2-digit number in character form. See 
[CURRENT-DATE], page 438, for more information. 


Hex-Digits (Nibble + 1:1) 
Assuming that Nibble is a numeric data item with a value in the range 0-15, 
and Hex-Digits is a PIC X(16) item with a value of 0123456789ABCDEF, this 
converts that numeric value to a hexadecimal digit. 


Table-Entry (6) (7:5) 
References characters 7 through 11 (5 characters in total) in the 6th occurrence 
of Table-Entry. 
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Reference modification may be used anywhere an identifier is legal, including serving as 
the receiving field of statements like MOVE (see [MOVE], page 352), STRING (see [STRING], 
page 401) and ACCEPT (see [ACCEPT], page 268), to name a few. 
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2.2.4. Arithmetic Expressions 


Arithmetic-Expression Syntax 


Unary-Expression-1 { **|* } Unary-Expression-2 


{ xl/ } 
Aes se Sy 
Unary-Expression Syntax } 

{ [ +l- ] { ( Arithmetic-Expression-1 ) } } 
{ { [ LENGTH OF ] { identifier-1 ae ae: 
{ ee See { literal-1 +} } 
{ { { Function-Reference } } } 
{ Arithmetic-Expression-2 } 


Arithmetic expressions are formed using four categories of operations — exponentiation, 
multiplication & division, addition & subtraction, and sign specification. 


In complex expressions composed of multiple operators and operands, a precedence of 
operation applies whereby those operations having a higher precedence are computed first 
before operations with a lower precedence. 


As is the case in almost any other programming language, the programmer is always 
free to use pairs of parenthesis to enclose sub-expressions of complex expressions that are to 
be evaluated before other sub-expressions rather than let operator precedence dictate the 
sequence of evaluation. 


In highest to lowest order of precedence, here is a discussion of each category of operation: 


Level 1 (Highest) — Unary Sign Specification (+ and - with a single argument) 
The unary “minus” (-) operator returns the arithmetic negation of its single 
argument, effectively returning as its value the product of its argument and -1. 


The unary “plus” (+) operator returns the value of its single argument, effec- 
tively returning as its value the product of its argument and +1. 


Level 2 — Exponentiation (** or ~) 
The value of the left argument is raised to the power indicated by the right 
argument. Non-integer powers are allowed. The ~ and ** operators are both 
supported to provide compatibility with programs written for other COBOL 
implementations. 


Level 3 — Multiplication (*) and division (/) 
The * operator computes the product of the left and right arguments while the 


/ operator computes the value of the left argument divided by the value of the 
right argument. If the right argument has a value of zero, expression evaluation 


Chapter 2 - COBOL Fundamentals 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 43 


will be prematurely terminated before a value is generated. This may cause 
program failure at run-time. 


A sequence of multiple 3rd-level operations (A * B / C, for example) will evalu- 
ate in strict left-to-right sequence if no parenthesis are used to control the order 
of evaluation. 


Level 4 — Addition (+) or subtraction (-) 
The + operator calculates the sum of the left and right arguments while the - 
operator computes the value of the right argument subtracted from that of the 
left argument. 


A sequence of multiple 4th-level operations (A - B + C, for example) will evalu- 


ate in strict left-to-right sequence if no parenthesis are used to control the order 
of evaluation. 


The syntactical rules of COBOL, allowing a dash (-) character in data item names, can 
lead to some ambiguity. 


o1 C PIC 9 VALUE 5. 
o1 OD PIC 9 VALUE 2. 
01 C-D PIC 9 VALUE 7. 
o1 iI PIC 9 VALUE 0. 


COMPUTE I=C-D+1 

The COMPUTE (see [COMPUTE], page 301) statement will evaluate the arithmetic ex- 
pression C-D+1 and then save that result in I. 

What value will be stored in I? The number 4, which is the result of subtracting the 
value of D (2) from the value of C (5) and then adding 1? Or, will it be the number 8, which 
is the value of adding 1 to the value of data item C-D (7)? 

The right answer is 8 — the value of data item C-D plus 1! Hopefully, that was the 
intended result. 

The GnuCOBOL compiler actually went through the following decision-making logic 
when generating code for the COMPUTE Statement: 

1. Is there a data item named C-D defined? If so, use its value for the character sequence 
C-D. 

2. If there is no C-D data item, then are there C and D data items? If not, the COMPUTE 
statement is in error. If there are, however, then code will be generated to subtract the 
value of D from C and add 1 to the result. 


Had there been at least one space to the left and/or the right of the -, there would have 
been no ambiguity — the compiler would have been forced to use the individual C and D 
data items. 


To avoid any possible ambiguity, as well as to improve program readability, it’s considered 
good COBOL programming practice to always code at least one space to both the left and 
right of every operator in arithmetic expressions as well as the = sign on a COMPUTE. 


Here are some examples of how the precedence of operations affects the results of arith- 
metic expressions (all examples use numeric literals, to simplify the discussion). 
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Expression Result 
Sra eA 13 

A PDT SA) 22 

(4 * 2) > 3-10 502 
Pf 25 ee 21S 14.85 


Notes 
* has precedence over + 


2°3 is 8 (~ has precedence over *), times 4 is 32, 
minus 10 is 22. 


Parenthesis provide for a recursive application of the 
arithmetic expression rules, effectively allowing you 
to alter the precedence of operations. 4 times 2 is 8 
(the use of parenthesis “trumps” the exponentiation 
operator, so the multiplication happens first); 8 * 3 
is 512, minus 10 is 502. 


Integer and non-integer operands may be freely 
intermixed 


Of course, arithmetic expression operands may be numeric data items (any USAGE 
except POINTER or PROGRAM POINTER) as well as numeric literals. 
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2.2.5. Conditional Expressions 


Conditional expressions are expressions which identify the circumstances under which a 
program may take an action or cease taking an action. As such, conditional expressions 


produce a value of TRUE or FALSE. 


There are seven types of conditional expressions, as discussed in the following sections. 


2.2.5.1. Condition Names 


These are the simplest of all conditions. Observe the following code: 
PIC 99V9. 


05 SHIRT-SIZE 


88 
88 
88 
88 
88 
88 
88 
88 
88 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


0 THRU 12.5 

13 THRU 13.5. 
14, 14. 
15, 15. 
16, 16. 
17, 17. 
18, 18. 
19, 19. 
20 THRU 99.9. 


annn#»n on 


The condition names TINY, XS, S, M, L, XL, XXL, XXXL and VERY-LARGE will have TRUE or 
FALSE values based upon the values within their parent data item (SHIRT-SIZE). 


A program wanting to test whether or not the current SHIRT-SIZE value can be classified 
as XL could have that decision coded as a combined condition (the most complex type of 


conditional expression), as either: 
IF SHIRT-SIZE 


-or- 


IF SHIRT-SIZE 


17 OR SHIRT-SIZE = 17.5 


Or it could simply utilize the condition name XL as follows: 


IF XL 
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2.2.5.2. Class Conditions 


[ 


Class-Condition Syntax 


identifier-1 IS [ NOT ] { NUMERIC 


} 
iia CS } 
{ ALPHABETIC } 
} 
} 


{ ALPHABETIC-LOWER 


A 
zg 
a 
zg 
z 
z 
2g 
zg 
zg 
zg 
z 
2 
2 
2g 
2g 
z 
zg 
Ww 


{ ALPHABETIC-UPPER } 


Wt 


{ class-name-1 


Class conditions evaluate the type of data that is currently stored in a data item. 


1. 


The NUMERIC class test considers only the characters ‘0’, ‘1’, ... , ‘9’ to be numeric; only 
a data item containing nothing but digits will pass a NUMERIC class test. Spaces, decimal 
points, commas, currency signs, plus signs, minus signs and any other characters except 
the digit characters will all fail NUMERIC class tests. 

The ALPHABETIC class test considers only upper-case letters, lower-case letters and 
spaces to be alphabetic in nature. 


The ALPHABETIC-LOWER and ALPHABETIC-UPPER class conditions consider only spaces 
and the respective type of letters to be acceptable in order to pass such a class test. 


4. The NOT option reverses the TRUE/FALSE value of the condition. 


Note that what constitutes a “letter” (or upper/lower case too, for that manner) 
may be influenced through the use of CHARACTER CLASSIFICATION specifications in 
the OBJECT-COMPUTER (see [OBJECT-COMPUTER], page 90) paragraph. 


Only data items whose USAGE (see [USAGE], page 232) is either explicitly or implicitly 
defined as DISPLAY may be used in NUMERIC or any of the ALPHABETIC class conditions. 


Some COBOL implementations disallow the use of group items or PIC A items with 
NUMERIC class conditions and the use of PIC 9 items with ALPHABETIC class conditions. 
GnuCOBOL has no such restrictions. 

The OMITTED class condition is used when it is necessary for a subprogram to deter- 
mine whether or not a particular argument was passed to it. In such class conditions, 
identifier-1 must be a linkage section item defined on the USING clause of the subpro- 
grams PROCEDURE DIVISION header. See [PROCEDURE DIVISION USING], page 248, 
for additional information. 


The class-name-1 option allows you to test for a user-defined class. Here’s an example. 


First, assume the following SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) definition 
of the user-defined class ‘Hexadecimal’: 


Chapter 2 - COBOL Fundamentals 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide AT 


SPECIAL-NAMES . 
CLASS Hexadecimal IS ’0’ THRU ’9’, ’A’ THRU ’F’, ’a’ THRU ’f’. 
Now observe the following code, which will execute the 150-Process-Hex-Value proce- 
dure if Entered-Value contains nothing but valid hexadecimal digits: 
IF Entered-Value IS Hexadecimal 
PERFORM 150-Process-Hex-Value 
END-IF 
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2.2.5.3. Sign Conditions 


Sign-Condition Syntax 


identifier-1 IS [ NOT ] { POSITIVE } 


mt OR ge ae ayo } 
{ NEGATIVE } 
; a } 
{ ZERO } 


Sign conditions evaluate the numeric state of a data item defined with a PICTURE (see 
[PICTURE], page 194) and/or USAGE (see [USAGE], page 232) that supports numeric values. 


1. A POSITIVE or NEGATIVE class condition will be TRUE only if the value of identifier-1 
is strictly greater than or less than zero, respectively. 


2. A ZERO class condition can be passed only if the value of identifier-1 is exactly zero. 
3. The NOT option reverses the TRUE/FALSE value of the condition. 
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2.2.5.4. Switch-Status Conditions 


In the SPECIAL-NAMES paragraph, an external switch name can be associated with one or 
more condition names. These condition names may then be used to test the ON/OFF 
status of the external switch. 


Here are the relevant sections of code in a program named testprog, which is designed 
to simply announce if SWITCH-1 is on: 


ENVIRONMENT DIVISION. 
SPECIAL-NAMES. 
SWITCH-1 ON STATUS IS Switch-1-Is-ON. 


PROCEDURE DIVISION. 


IF Switch-1-Is-ON 
DISPLAY "Switch 1 Is On" 
END-IF 


The following are two different command window sessions — the left on a 
Unix/Cygwin/OSX system and the right on a windows system — that will set the switch 
on and then execute the testprog program. Notice how the message indicating that the 
program detected the switch was set is displayed in both examples: 


$ COB_SWITCH_1=ON C:>SET COB_SWITCH_1=0N 
$ export COB_SWITCH_1 C:>testprog 

$ ./testprog Switch 1 Is On 

Switch 1 Is On C:> 

$ 
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2.2.5.5. Relation Conditions 


[ 


Relation-Condition Syntax 


AAA A 


identifier-1 } IS [ NOT ] RelOp { identifier-2 } 
literal-1 } apie { literal-2 } 
arithmetic-expression-1 } { arithmetic-expression-2 } 
index-name-1 } { index-name-2 } 


RelOp Syntax 


RAHA AHH AHA AHA AAA 


EQUAL TO 


LESS THAN OR EQUAL TO 


Fa 
tA 
n 
n 
co | 
aa] 
> 
SB 
DEY YY YY YY YY 


These conditions evaluate how two different values "relate" to each other. 


1. 


When comparing one numeric value to another, the USAGE (see [USAGE], page 232) 
and number of significant digits in either value are irrelevant as the comparison is 
performed using the actual algebraic values. 


When comparing strings, the comparison is made based upon the program’s collat- 
ing sequence. When the two string arguments are of unequal length, the shorter is 
assumed to be padded (on the right) with a sufficient number of spaces as to make 
the two strings of equal length. String comparisons take place on a corresponding 
character-by-character basis, left to right, until the TRUE/FALSE value for the relation 
test can be established. Characters are compared according to their relative position 
in the program’s COLLATING SEQUENCE (as defined in SPECIAL-NAMES (see [SPECIAL- 
NAMES], page 92)), not according to the bit-pattern values the characters have in 
storage. 
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3. By default, the program’s COLLATING SEQUENCE will, however, be based entirely on the 
bit-pattern values of the various characters. 


4. There is no functional difference between using the wordy version (IS EQUAL TO, IS 
LESS THAN, ...) versus the symbolic version (=, <, ...) of the actual relation operators. 
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2.2.5.6. Combined Conditions 


[ 


Combined Condition Syntax 


[ € ] Condition-1 [ ) ] { AND } [ ( ] Condition-2 [ ) ] 


oe 
{OR } 
dee he ae 


A combined condition is one that computes a TRUE/FALSE value from the TRUE/FALSE values 
of two other conditions (which could themselves be combined conditions). 


1. 


If either condition has a value of TRUE, the result of ORing the two together will result 
in a value of TRUE. ORing two FALSE conditions will result in a value of FALSE. 
In order for AND to yield a value of TRUE, both conditions must have a value of TRUE. 
In all other circumstances, AND produces a FALSE value. 
When chaining multiple, similar conditions together with the same operator 
(OR/AND), and left or right arguments have common subjects, it is possible to 
abbreviate the program code. For example: 

IF ACCOUNT-STATUS = 1 OR ACCOUNT-STATUS = 2 OR ACCOUNT-STATUS = 7 
Could be abbreviated as: 

IF ACCOUNT-STATUS = 1 OR 2 OR 7 


Just as multiplication takes precedence over addition in arithmetic expressions, so does 
AND take precedence over OR in combined conditions. Use parenthesis to change this 
precedence, if necessary. For example: 


FALSE AND FALSE OR TRUE AND TRUE 
Evaluates to TRUE 


(FALSE AND FALSE) OR (TRUE AND TRUE) 
Evaluates to TRUE (since AND has precedence over OR) - this is identical 
to the previous example 


(FALSE AND (FALSE OR TRUE) ) AND TRUE 
Evaluates to FALSE 
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2.2.5.7. Negated Conditions 


Negated Condition Syntax } 


NOT Condition-1 


A condition may be negated by prefixing it with the NOT operator. 


1. The NOT operator has the highest precedence of all logical operators, just as a unary 
minus sign (which “negates” a numeric value) is the highest precedence arithmetic 
operator. 

2. Parenthesis must be used to explicitly signify the sequence in which conditions are 
evaluated and processed if the default precedence isn’t desired. For example: 


NOT TRUE AND FALSE AND NOT FALSE 
Evaluates to FALSE AND FALSE AND TRUE which evaluates to FALSE 


NOT (TRUE AND FALSE AND NOT FALSE) 
Evaluates to NOT (FALSE) which evaluates to TRUE 


NOT TRUE AND (FALSE AND NOT FALSE) 
Evaluates to FALSE AND (FALSE AND TRUE) which evaluates to FALSE 
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2.2.6. Use of Periods 


All COBOL implementations distinguish between sentences and statements in the procedure 
division. A Statement is a single executable COBOL instruction. For example, these are 
all statements: 

MOVE SPACES TO Employee-Address 

ADD 1 TO Record-Counter 

DISPLAY "Record-Counter=" Record-Counter 

Some COBOL statements have a scope of applicability associated with them where one 
or more other statements can be considered to be part of or related to the statement in 
question. An example of such a situation might be the following, where the interest on a 
loan is being calculated and displayed at 4% interest if the loan balance is under $10,000, 
and 4.5% otherwise. (WARNING: the following code has an error!): 

IF Loan-Balance < 10000 

MULTIPLY Loan-Balance BY 0.04 GIVING Interest 
ELSE 

MULTIPLY Loan-Balance BY 0.045 GIVING Interest 
DISPLAY "Interest Amount = " Interest 

In this example, the IF statement actually has a scope that can include two sets of 
associated statements: one set to be executed when the IF (see [IF], page 338) condition is 
TRUE, and another if it is FALSE. 

Unfortunately, there’s a problem with the above. A human being looking at that code 
would probably infer that the DISPLAY (see [DISPLAY], page 305) statement, because of its 
lack of indentation, is to be executed regardless of the TRUE/FALSE value of the IF condition. 
Unfortunately, the compiler (any COBOL compiler) won’t see it that way because it really 
couldn’t care less what sort of indentation, if any, is used. In fact, any COBOL compiler 
would be just as happy to see the code written like this: 

IF Loan-Balance < 10000 MULTIPLY Loan-balance 
BY 0.04 GIVING Interest ELSE MULTIPLY 
Loan-Balance BY 0.045 GIVING Interest DISPLAY 
"Interest Amount = " Interest 

How then do we inform the compiler that the DISPLAY statement is outside the scope of 
the IF? 

That’s where sentences come in. 

A COBOL Sentence is defined as any arbitrarily long sequence of statements, followed 
by a period (.) character. The period character is what terminates the scope of a set of 
statements. Therefore, our example should have been coded like this: 

IF Loan-Balance < 10000 

MULTIPLY Loan-Balance BY 0.04 GIVING Interest 
ELSE 

MULTIPLY Loan-Balance BY 0.045 GIVING Interest. 
DISPLAY "Interest Amount = " Interest 

See the period at the end of the second MULTIPLY (see [MULTIPLY], page 354)? That 
is what terminates the scope of the IF, thus making the DISPLAY statement’s execution 
completely independent of the TRUE/FALSE status of the IF. 
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2.2.7. Use of VERB/END-VERB Constructs 


Prior to the 1985 COBOL standard, using a period character was the only way to signal 
the end of a statement’s scope. 
Unfortunately, this caused some problems. Take a look at this code: 
IF A= 1 
IF B= 1 
DISPLAY "A & B = i" 
ELSE *> This ELSE has a problem! 
IFB=1 
DISPLAY "A NOT = 1 BUT B = 1" 
ELSE 
DISPLAY "NEITHER A NOR B = i". 


The problem with this code is that indentation — so critical to improving the human- 
readability of a program — can provide an erroneous view of the logical flow. An ELSE 
is always associated with the most-recently encountered IF; this means the emphasized 
ELSE will be associated with the IF B= 1 statement, not the IF A= 1 statement as the 
indentation would appear to imply. 


This sort of problem led to a band-aid solution being added to the COBOL language: 
the NEXT SENTENCE clause: 


IF A= 1 
LF UBS =: 
DISPLAY "A & B = 1" 
ELSE 
NEXT SENTENCE 
ELSE 
TF Bs = 1 
DISPLAY "A NOT = 1 BUT B = i" 
ELSE 


DISPLAY "NEITHER A NOR B = 1". 


NEXT SENTENCE informs the compiler that if the B = 1 condition is false, control should 
fall into the first statement that follows the next period. 


With the 1985 standard for COBOL, a much more elegant solution was introduced. Any 
COBOL Verb (the first reserved word of a statement) that needed such a thing was allowed 
to use an END-verb construct to end its scope without disrupting the scope of any other 
statement it might have been in. Any COBOL 85 compiler would have allowed the following 
solution to our problem: 


IF A= 1 
IF B= 1 
DISPLAY "A & B = 1" 
END-IF 
ELSE 
IF B= 1 
DISPLAY "A NOT = 1 BUT B = i" 
ELSE 
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DISPLAY "NEITHER A NOR B = 1". 


This new facility made the period almost obsolete, as our program segment would prob- 
ably be coded like this today: 


IF A= 1 
IF B= 1 
DISPLAY "A & B = 1" 
END-IF 
ELSE 
IF B= 1 
DISPLAY "A NOT = 1 BUT B = i" 
ELSE 
DISPLAY "NEITHER A NOR B = 1" 
END-IF 
END-IF 


COBOL (GnuCOBOL included) still requires that each procedure division paragraph 
contain at least one sentence if there is any executable code in that paragraph, but a 
popular coding style is now to simply code a single period right before the end of each 
paragraph. 

The standard for the COBOL language shows the various END-verb clauses are optional 
because using a period as a scope-terminator remains legal. 

If you will be porting existing code over to GnuCOBOL, you'll find it an accommodating 
facility capable of conforming to whatever language and coding standards that code is likely 
to use. If you are creating new GnuCOBOL programs, however, I would strongly counsel 
you to use the END-verb structures in those programs. 
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2.2.8. Concurrent Access to Files 


The manipulation of data files is one of the COBOL language’s great strengths. There 
are features built into COBOL to deal with the possibility that multiple programs may be 
attempting to access the same file concurrently. Multiple program concurrent access is dealt 
with in two ways — file sharing and record locking. 


Not all GnuCOBOL implementations support file sharing and record-locking options. 
Whether they do or not depends upon the operating system they were built for and the 
build options that were used when the specific GnuCOBOL implementation was generated. 


2.2.8.1. File Sharing 


GnuCOBOL controls concurrent-file access at the highest level through the concept of file 
sharing, enforced when a program attempts to open a file. This is accomplished via a 
UNIX operating-system routine called fcntl. That module is not currently supported by 
Windows and is not present in the MinGW Unix-emulation package. GnuCOBOL builds 
created using a MinGW environment will be incapable of supporting file-sharing controls 
— files will always be shared in such environments. A GnuCOBOL build created using the 
Cygwin environment on Windows would have access to fcntl and therefore will support 
file sharing. Of course, actual Unix builds of GnuCOBOL, as well as OSX builds, should 
have no issues because fcnt1 should be available. 


Any limitations imposed on a successful OPEN (see [OPEN], page 358) will remain in 
place until your program either issues a CLOSE (see [CLOSE], page 299) against the file or 
the program terminates. 


File sharing is controlled through the use of a SHARING clause: 
SHARING WITH { ALL OTHER } 


popmcma 1 a } 
{ NO OTHER } 
ee } 
{ READ ONLY } 


This clause may be used either in the file’s SELECT statement (see [SELECT], page 104), 
on the OPEN statement (see [OPEN], page 358) which initiates your program’s use of the 
file, or both. If a SHARING option is specified in both places, the specifications made on the 
OPEN statement will take precedence over those from the SELECT statement. 


Here are the meanings of the three options: 


ALL OTHER When your program opens a file with this sharing option in effect, no restrictions 
will be placed on other programs attempting to OPEN the file after your program 
did. This is the default sharing mode. 


NO OTHER When your program opens a file with this sharing option in effect, your program 
announces that it is unwilling to allow any other program to have any access to 
the file as long as you are using that file; OPEN attempts made in other programs 
will fail with a file status of 37 (PERMISSION DENIED) until such time as you 
CLOSE (see [CLOSE], page 299) the file. 
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READ ONLY Opening a file with this sharing option indicates you are willing to allow other 
programs to OPEN the file for input while you have it open. If they attempt any 
other OPEN, theirs will fail with a file status of 37. Of course, your program 
may fail if someone else got to the file first and opened it with a sharing option 
that imposed file-sharing limitations. 


If the SELECT of a file is coded with a FILE STATUS clause, OPEN failures — including those 
induced by sharing failures — will be detectable by the program and a graceful recovery 
(or at least a graceful termination) will be possible. If no such clause was coded, however, 
a runtime message will be issued and the program will be terminated. 
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2.2.8.2. Record Locking 


Record-locking is supported by advanced file-management software built-in to the Gnu- 
COBOL implementation you are using. This software provides a single point-of-control for 
access to files — usually ORGANIZATION INDEXED files. One such runtime package capable 
of doing this is the Berkeley Database (BDB) package — a package frequently used in 
GnuCOBOL builds to support indexed files. 

The various I/O statements your program can execute are capable of imposing limitations 
on access by other concurrently-executing programs to the file record they just accessed. 
These limitations are syntactically imposed by placing a lock on the record using a LOCK 
clause. Other records in the file remain available, assuming that file-sharing limitations 
imposed at the time the file was opened didn’t prevent access to the entire file. 


1. If the GnuCOBOL build you are using was configured to use the Berkeley Database 


(BDB) package for indexed file I/O, record locking will be available by using the 
DB_HOME run-time environment variable. 


2. If the SELECT (see [SELECT], page 104) statement or file OPEN (see [OPEN], page 358) 
specifies SHARING WITH NO OTHER, record locking will be disabled. 


3. If the file’s SELECT contains a LOCK MODE IS AUTOMATIC clause, every time a record is 
read from the file, that record is automatically locked. Other programs may access 
other records within the file, but not a locked record. 


4. If the file’s SELECT contains a LOCK MODE IS MANUAL clause, locks are placed on records 
only when a READ statement executed against the file includes a LOCK clause (this clause 
will be discussed shortly). 


5. If the LOCK ON clause is specified in the file’s SELECT, locks (either automatically or 
manually acquired) will continue to accumulate as more and more records are read, 
until they are explicitly released. This is referred to as multiple record locking. 


Locks acquired via multiple record locking remain in effect until the program holding 
the lock... 


e ...terminates, or... 
e ...executes a CLOSE statement (see [CLOSE], page 299) against the file, or ... 
e ...executes an UNLOCK statement (see [UNLOCK], page 412) against the file, or 


e ...executes a COMMIT statement (see [COMMIT], page 300) or ... 
e ...executes a ROLLBACK statement (see [ROLLBACK], page 376). 


6. If the LOCK ON clause is not specified, then the next I/O statement your program 
executes, except for START (see [START], page 397), will release the lock. This is 
referred to as single record locking. 


7. A LOCK clause, which may be coded on a READ (see [READ], page 366), REWRITE (see 
[REWRITE], page 374) or WRITE statement (see [WRITE], page 417) looks like this: 


{ IGNORING LOCK } 


nana i Same ac oed } 
{ WITH [ NO ] LOCK } 
{ EE 
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{ WITH KEPT LOCK } 


de ee ee eS } 
{ WITH IGNORE LOCK } 
et Re Stree } 
{ WITH WAIT } 


The WITH [ NO J] LOCK option is the only one available to REWRITE or WRITE statements. 


The meanings of the various record locking options are as follows: 


IGNORING LOCK 
WITH IGNORE LOCK 


WITH LOCK 


These options (which are synonymous) inform GnuCOBOL that any locks 
held by other programs should be ignored. 


Access to the record by other programs will be denied. 


WITH NO LOCK 


The record will not be locked. This is the default for all statements. 


WITH KEPT LOCK 


WITH WAIT 


When single record locking is in effect, as a new record is accessed, locks 
held for previous records are released. By using this option, not only is the 
newly accessed record locked (as WITH LOCK would do), but prior record 
locks will be retained as well. A subsequent READ without the KEPT LOCK 
option will release all “kept” locks, as will the UNLOCK statement. 


This option informs GnuCOBOL that the program is willing to wait for a 
lock held (by another program) on the record being read to be released. 


Without this option, an attempt to read a locked record will be immediately 
aborted and a file status of 51 will be returned. 


With this option, the program will wait for a preconfigured time for the 
lock to be released. If the lock is released within the preconfigured wait 
time, the read will be successful. If the preconfigured wait time expires 
before the lock is released, the read attempt will be aborted and a 51 file 
status will be issued. 


End of Chapter 2 — COBOL Fundamentals 
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3. CDF - Compiler Directing Facility 


The Compiler Directing Facility, or CDF, is a means of controlling the compilation of Gnu- 
COBOL programs. CDF provides a mechanism for dynamically setting or resetting certain 
compiler switches, introducing new source code from one or more source code libraries, 
making dynamic source code modifications and conditionally processing or ignoring source 
statements altogether. This is accomplished via a series of special CDF statements and 
directives that will appear in the program source code. 


When the compiler is operating in Fixed Format Mode, all CDF statements must begin 
in column seven (7) or beyond. 

There are two types of supported CDF statements in GnuCOBOL — Text Manipulation 
Statements and Compiler Directives. 

The CDF text manipulation statements COPY and REPLACE are used to introduce new 
code into programs either with or without changes, or may be used to modify existing 
statements already in the program. Text manipulation statements are always terminated 
with a period. 

CDF directives, denoted by the presence of a >> character sequence as part of the 
statement name itself, influence the process of program compilation. 

Compiler directives are never terminated with a period. 


The compiler command-line option -D offers additional control (see (undefined) [cobe - 
The GnuCOBOL Compiler], page (undefined) ). 
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3.1. >>CALL-CONVENTION 


[ CDF >>CALL-CONVENTION Syntax 


>>CALL-CONVENTION { COBOL } 


Peete mci natal npn { EXTERN } 
{ STDCALL } 
{ STATIC } 


This directive instructs the compiler how to treat references to program names and may be 
used to determine other details for interacting with a function or program. There are four 
options with COBOL being the default. 


COBOL The program name is treated as a COBOL word that maps to the externalised 
name program to be called, cancelled or referenced in the program-address- 
identifier, applying the same mapping rules as for a program name for which 
no AS phrase is specified. (The is the default.) 


EXTERN The program name is treated as an external reference. 
STDCALL [more info needed] 


STATIC The program name is called as a included element and not dynamically which 
is the normal default. 
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3.2. COPY 
f CDF COPY Statement Syntax ] 
COPY copybook-name 
[ IN|OF library-name ] 
[ SUPPRESS PRINTING ] 
[ REPLACING { Phrase-Clause | String-Clause }... ] 
[ CDF COPY Phrase-Clause Syntax ] 
{ ==pseudo-text-1== } BY { ==pseudo-text-2== } 
{ identifier-1 } ~~ { identifier-2 } 
{ literal-1 } { literal-2 } 
{ word-1 } { word-2 } 
[ CDF COPY String-Clause Syntax ] 


me 


COPY statements are used to import copybooks (see [Copybooks], page 14) into a pro- 
gram. 


COPY statements may be used anywhere within a COBOL program where the code 
contained within the copybook would be syntactically valid. 


The optional SUPPRESS clause (with or without the optional PRINTING reserved word) 
is valid syntactically but is non-functional. It is supported to facilitate compatibility 
with source code written for other versions of COBOL. 


There is no difference between the use of the word IN and the word OF — use the one 
you prefer. 

A period is absolutely mandatory at the end of every COPY statement, even if the state- 
ment occurs within the scope of another one where a period might appear disruptive, 
such as within the scope of an IF (see [IF], page 338) statement. This mandatory 
period at the end of the statement does not, however, affect the statement scope in 
which the COPY occurs. 
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Both pseudo-text-2 and partial-word-2 may be null. 


All COPY statements are located and the contents of the corresponding copybooks in- 
serted into the program source code before the actual compilation process begins. If a 
copybook contains a COPY statement, the copybook insertion process will be repeated 
to resolve the embedded COPY. This will continue until no unresolved COPY statements 
remain. At that point, actual program compilation will begin. 


See [Locating Copybooks], page 644, for the specific rules on how copybooks are located 
by the compiler. 


The optional REPLACING clause allows for one or more of either of the following kinds 
of text replacements to be made: 


Phrase-Clause 
Replacement of one or more complete reserved words, user-defined identi- 
fiers or literals; the following points apply to this option: 


e This option cannot be used to replace part of a word, identifier or 
literal. 


e Whatever precedes the BY will be referred to here as the search string. 


e Single-item search strings can be specified by coding the identifier- 
1, literal-1 or word-1 being replaced. 


e Multiple-item search strings can be specified using the ==pseudo- 
text-1== option. For example, to replace all occurrences of UPON 
PRINTER, you would specify ==UPON PRINTER==. 


e The replacement string, which follows the BY, may be specified using 
any of the four options. 


e If the replacement string is a multiple-item phrase or is to be deleted 
altogether, you must use the ==pseudo-text-2== option. If pseudo- 
text-2 is null (in other words, the replacement text is specified as 
====), all encountered occurrences of the search string will be deleted. 


String-Clause 
Using this, you may replace character sequences that occur at the beginning 
(see LEADING) or end (see TRAILING) of reserved or user-defined words. 
For example, to change all words of the form "0100-xxxxxx" to "020- 
xxxxxx", code LEADING ==0100-== BY ==020-==. To simply remove all 
"0100-" prefixes from words, code LEADING ==0100-== BY ====. 
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3.3. REPLACE 


f CDF REPLACE Statement (Format 1) Syntax | 


REPLACE [ ALSO ] { Phrase-Clause | String-Clause }... 


f CDF REPLACE Statement (Format 2) Syntax 


REPLACE [ LAST ] OFF . 


CDF REPLACE Phrase-Clause Syntax } 


{ ==pseudo-text-1== } BY { ==pseudo-text-2== 


CDF REPLACE String-Clause Syntax 


[ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2== 


1. The REPLACE statement provides a mechanism for changing all or part of one or more 
GnuCOBOL statements. 

2. A period is absolutely mandatory at the end of every REPLACE statement (either for- 
mat), even if the statement occurs within the scope of another one where a period might 
appear disruptive (such as within the scope of an IF (see [IF], page 338) statement; 
the period will not, however, affect the statement scope in which the REPLACE occurs. 

3. The following points apply to Format 1 of the REPLACE statement: 

A. Format 1 of the REPLACE statement can be used to make changes to program source 
code in much the same way as the REPLACING option of the COPY statement can, 
via these options: 


Phrase-Clause 
Replace one or more complete reserved words, user-defined identifiers 
or literals; the following points apply to this option: 
e This option cannot be used to replace part of a word, identifier 
or literal. 
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e Whatever precedes the BY will be referred to here as the search 
string. 

e Search strings on REPLACE are always specified using the 
==pseudo-text-1== option. For example, to replace all 
occurrences of UPON PRINTER, you would specify ==UPON 
PRINTER==. 


e The replacement string, which follows the BY, is specified using the 
==pseudo-text-2== option. If pseudo-text-2 is null (in other 
words, the replacement text is specified as ====), all encountered 
occurrences of the search string will be deleted. 


String-Clause 
Using this, you may replace character sequences that occur at 
the beginning (see LEADING) or end (see TRAILING) of reserved 
or user-defined words. For example, to change all words of the 
form "0100-xxxxxx" to "020-xxxxxx", code LEADING ==0100-== BY 
==020-==. To simply remove all "0100-" prefixes from words, code 
LEADING ==0100-== BY ====. 


. Once a Format 1 REPLACE statement is encountered in the currently-compiling 


source file, Replace Mode becomes active, and the change(s) specified by that 
statement will be automatically made on all subsequent source statements the 
compiler reads from the file. 


Replace Mode remains in-effect — continuing to make source code changes — until 
another Format 1 REPLACE is encountered, the end of currently compiling program 
source file is reached or a Format 2 REPLACE statement is encountered. 


. When a Format 1 REPLACE statement with the ALSO keyword is encountered 


without Replace Mode being currently active, the effect will be as if the ALSO had 
not been specified. If Replace Mode already was in effect, the effect will be to 
“push” the current change specification(s) onto the top of a stack and add the 
specification(s) of the new statement to those that were already in effect. 


When a Format 1 REPLACE without the ALSO keyword is encountered, any stacked 
change specification(s), if any, will be discarded and the currently in-effect change 
specification(s), if any, will be replaced by those of the new statement. 


When the end of the currently-compiling source file is reached, Replace Mode is 
deactivated and any stacked replace specifications will be discarded — compilation 
of the next source file (if any) will begin with Replace Mode inactive and no change 
specification(s) on the stack. 


4. The following points apply to Format 2 of the REPLACE statement: 


A. 


B. 


If Replace Mode is currently inactive, the Format 2 REPLACE statement will be 
ignored. 

If Replace Mode is currently active, a REPLACE OFF. will deactivate Replace Mode 
and discard any replace specification(s) on the stack. The compiler will henceforth 
operate as if no REPLACE had ever been encountered, until such time as another 
Format 1 REPLACE is encountered. 
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C. If Replace Mode is currently active, a REPLACE LAST OFF. will replace the current 
replace specification(s) with those popped off the top of the stack. If there were 
no replace specification(s) on the stack, the effect will be as if a REPLACE OFF. had 
been coded. 
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3.4. >>DEFINE 


[ 


CDF >>DEFINE Directive Syntax 


>>DEFINE [ CONSTANT ] cdf-variable-1 AS { OFF } 


a as Coca } 


{ literal-1 [ OVERRIDE ] } 


RY. | ee A } 
{ PARAMETER [ OVERRIDE ] } 


Use the >>DEFINE CDF directive to create CDF variables and (optionally) assign them 
either literal or environment variable values. 


1. 


The reserved word AS is optional and may be included, or not, at the discretion of the 
programmer. The presence or absence of this word has no effect upon the program. 


CDF variables defined in this way become undefined once an END PROGRAM or END 
FUNCTION directive is encountered in the input source. 

The >>DEFINE CDF directive is one way to create CDF variables that may be processed 
by other CDF statements such as >>IF (see [>>IF], page 69). The >>SET CDF directive 
(see [>>SET], page 71) provides another way to create them. 


CDF variable names follow the rules for standard GnuCOBOL user-defined names, 
and may not duplicate any CDF reserved word. CDF variable names may duplicate 
COBOL reserved words, provided the CONSTANT option is not specified, but such names 
are not recommended. 

The CONSTANT option is valid only in conjunction with literal-1. When CONSTANT is 
specified, the CDF variable that is created may be used within your regular COBOL 
code as if it were a literal value. Without this option, the CDF variable may only 
be referenced on other CDF statements. The OFF option is used to create a variable 
without assigning it any value. 

The PARAMETER option is used to create a variable whose value is that of the environ- 
ment variable of the same name. Note that this value assignment occurs at compilation 
time, not program execution time. 

In the absence of the OVERRIDE option, cdf-variable-1 must not yet have been defined. 
When the OVERRIDE option is specified, cdf-variable-1 will be created with the specified 
value, if it had not yet been defined. If it had already been defined, it will be redefined 
with the new value. 
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3.5. >>IF 


69 


[ CDF >>IF Directive Syntax 


>>IF CDF-Conditional-Expression-1 
aha [ Program-Source-Lines-1 ] 


[ >>ELIF CDF-Conditional-Expression-2 
EIS [ Program-Source-Lines-2 ] ]... 


[ >>ELSE 


[ Program-Source-Lines-3 ] ] 


>>END-IF 


CDF-Conditional-Expression Syntax 


{ cdf-variable-1 } IS [ NOT ] { DEFINED 
{ literal-1i } Saree Wietotetatedatee 


{ CDF-Rel0p { cdf-variable-2 


} 
{ { literal-2 } 


wee Ye 


CDF-RelOp Syntax 


>= or GREATER THAN OR EQUAL TO 
> or GREATER THAN 

<= or LESS THAN OR EQUAL TO 

< or LESS THAN 


= or EQUAL TO 


<> or EQUAL TO (with "NOT") 
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The >>IF CDF directive causes the GnuCOBOL compiler to process or ignore COBOL 
source statements, CDF text-manipulation statements and CDF directives depending upon 
the value of one or more conditional expressions based upon CDF variables. 


1. The reserved words IS, THAN and TO are optional and may be omitted. The presence 
or absence of these words has no effect on the program. 


2. Each >>IF directive must be terminated by an >>END-IF directive. 


3. There may be any number of >>ELIF clauses following an >>IF, including zero. 


4. There may no more than one >>ELSE clause following an >>IF. When >>ELSE is used, 
it must follow the >>IF and all >>ELIF clauses. 


5. Only one of the Program-Source-Lines-n block of statements that lie within the scope 
of the >>IF ... >>END-IF may be processed by the compiler. Which one (if any) that 
gets processed will be decided as follows: 


A. 


Each CDF-Conditional-Expression-n will be evaluated, in turn, in the sequence 
in which they are coded in the >>IF statement and any >>ELIF clauses that may 
be present until one evaluates to TRUE. Once one of them evaluates to TRUE, 
the Program-Source-Lines-n block of code that corresponds to the TRUE CDF- 
Conditional-Expression-n will be one that is processed. All others within the 
>>IF->>END-IF scope will be ignored. 


. If no CDF-Conditional-Expression evaluates to TRUE, and there is an >>ELSE 


clause, the Program-Source-Lines-3 block of statements following the >>ELSE 
clause will be processed by the compiler and all others within the >>IF->>END-IF 
scope will be ignored. 


. If no CDF-Conditional-Expression-n evaluates to TRUE and there is no >>ELSE 


clause, then none of the Program-Source-Lines-n block of statements within the 
>>IF->>END-IF scope will be processed by the compiler. 


. If the Program-Source-Lines-n> statement block selected for processing is empty, 


no error results — there will just be no code generated from the >>IF->>END-IF 
structure. 


6. A Program-Source-Lines-n block may contain any valid COBOL or CDF code. 


7. The following points pertain to any CDF-Conditional-Expression-n: 


A. 


D. 


The DEFINED option tests for whether cdf-variable-1 has been defined, but not yet 
assigned a value (>>DEFINE ... OFF); use the NOT option to test for the variable 
not being defined. 


. The SET option tests for whether cdf-variable-1 has been given a value, either via 


a >>SET statement or via a >>DEFINE without the OFF option. 


Two CDF variables, two literals or a single CDF variable and a single literal may 
be compared against each other using a relational operator. Unlike the standard 
GnuCOBOL IF statement (see [IF], page 338), multiple comparisons cannot be 
ANDed or ORed together; you may nest a second >>IF inside the first, however, to 
simulate an AND and an OR may be simulated via the >>ELIF option. 


The <> symbol stands for NOT EQUAL TO. 
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3.6. >>SET 


[ 


CDF >>SET Directive Syntax 


>>SET { [ CONSTANT ] cdf-variable-1 literal-1 ] 


Bs 
} 


{ SOURCEFORMAT AS FIXED|FREE|VARIABLE| XOPEN|XCARD|CRT|TERMINAL|COBOLX } 


The >>SET CDF directive provides an alternate means of performing the actions of the 
>>DEFINE and >>SOURCE directives, as well as a means of controlling the compiler’s -free 
switch, -fixed switch and -ffold-copy switch from within program source code. 


1. 


The reserved word AS is optional (only on the SOURCEFORMAT and FOLDCOPYNAME 
clauses) and may be included, or not, at the discretion of the programmer. The 
presence or absence of this word has no effect upon the program. 

CDF variables defined in this way become undefined once an END PROGRAM or END 
FUNCTION directive is encountered in the input source. 

The FOLDCOPYNAME option provides the equivalent of specifying the compiler -ffold- 
copy=xxx switch, where xxx is either UPPER or LOWER. 

The NOFOLDCOPYNAME option turns off the effect of either the >>SET FOLDCOPYNAME 
statement or the compiler -ffold-copy=xxx switch. 

If the CONSTANT option is used, literal-1 must also be used. This option provides 
another means of defining constants that may be used anywhere in the program that 
a literal could be specified. 

The remaining options of the >>SET CDF directive provide equivalent functionality 
to the >>DEFINE | how ever as this form is no longer in the Cobol standards and is 
classsed as archaic and wil be so flagged, the use of >>DEFINE should be used for all 
new programs |, and >>SOURCE directives, as follows: 


>>SET cdf-variable-1 
>>DEFINE cdf-variable-1 AS OFF 


>>SET cdf-variable-1 AS literal-1 
>>DEFINE cdf-variable-1 AS literal-1 


>>SET CONSTANT cdf-variable-1 literal-1 
>>DEFINE CONSTANT cdf-variable-1 literal-1 


>>SET SOURCEFORMAT AS FIXED 
>>SOURCE FORMAT IS FIXED 
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>>SET SOURCEFORMAT AS FREE 
>>SOURCE FORMAT IS FREE 


>>SET SOURCEFORMAT AS VARIABLE 
>>SOURCE FORMAT IS 


>>SET SOURCEFORMAT AS XOPEN 
>>SOURCE FORMAT IS XOPEN 


>>SET SOURCEFORMAT AS XCARD 
>>SOURCE FORMAT IS XCARD 


>>SET SOURCEFORMAT AS CRT 
>>SOURCE FORMAT IS CRT 


>>SET SOURCEFORMAT AS TERMINAL 
>>SOURCE FORMAT IS TERMINAL 


>>SET SOURCEFORMAT AS COBOLX 
>>SOURCE FORMAT IS COBOLX 


>>SET XFD literal-1 
[See chapter 13] 


>>SET Micro-Focus-—Directive 


[to do] 
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3.7. >>SOURCE 


[ CDF >>SOURCE Directive Syntax | 


>>SOURCE FORMAT IS { FIXED|FREE|VARIABLE|XOPEN|XCARD|CRT|TERMINAL|COBOLX } 


The >>SOURCE CDF directive puts the compiler into FIXED or FREE source-code format 
mode. This, in effect, provides yet another mechanism for controlling the compiler’s 
-free switch and -fixed switch. 

1. The reserved words FORMAT and IS are optional and may be included, or not, at the 
discretion of the programmer. The presence or absence of these words has no effect 
upon the program. 

2. FIXED : Source code is divided into: columns 1-6, the sequence number area; column 
7, the indicator area; columns 8-72, the program-text area; and columns 72-80 as the 
reference area. 

3. FREE : Source code text area starts in column 1 and continues till the end of line (to 
a maximum of 255 characters). 

4. VARIABLE : Identical to FIXED format above except that it extends up to column 
256 (in MF and some others, it is 252). 

5. XOPEN : X/Open Free-form format. The program-text area may start in column 1 
unless an indicator is present, and lines may contain up to 80 characters. Indicator for 
debugging lines is D instead of D or d. 

6. XCARD : ICOBOL xCard format. Variable format with right margin set at column 
255 instead of 250. 

7. CRT : ICOBOL Free-form format (CRT). Similar to the X/Open format above, with 
lines containing up to 320 characters and single-character debugging line indicators (D 
or d). 

8. TERMINAL : ACUCOBOL-GT Terminal format. Similar to the CRT format above, 
with indicator for debugging lines being \D instead of D or d. This format is mostly 
compatible with VAX COBOL terminal source format. 

9. COBOLX : This format is similar to the CRT format above, except that the indicator 
area is always present in column 1; the program-text area starts in column 2 and 
extends up to the end of the record. Lines may contain up to 255 characters. 

10. Note that with source formats XOPEN, CRT, TERMINAL, and COBOLX, missing 
spaces are not inserted within continued alphanumeric literals that are truncated before 
the right margin 

11. You may switch between the various format modes as desired and it takes effect im- 
mediately. 


12. You may also use the >>SET CDF directive to perform this function. 


13. If the compiler is already in the specified mode, this statement will have no effect. 
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3.8. >>TURN 


[ CDF >>TURN Directive Syntax 
>>TURN { exception-name-1 [ file-name-1 ]... }... 
{ OFF } 
ener } 
{ CHECKING ON [ WITH LOCATION ] } 


The directive will (de-)activate exception checks. 
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3.9. >>D 


[ CDF >>D Directive Syntax 


The directive removes all floating debug lines if debug mode not active. Otherwise will 
ignore the directive part of the line. 
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3.10. >>DISPLAY 


[ CDF >>DISPLAY Directive Syntax 


>>DISPLAY source-text [ VCS = version-string ] 


The directive is a v1.0 extension and will display messages during compilation. 


Chapter 3 - CDF - Compiler Directing Facility 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 77 


3.11. >>PAGE 


[ CDF >>PAGE Directive Syntax ] 


>>PAGE [ comment-text ] 


The PAGE directive specifies page ejection and provides documentation for the source 
listing. 
1. Comment-Text may contain any character in the computers standard character coded 
set except for control characters. 
2. Comment-Text is not checked for syntax and only serves as documentation. 


3. if a source listing is being produced a PAGE directive shall cause page ejection followed 
by listing of the PAGE directive. 


4. If a listing is not being produced the directive will have no effect. 
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3.12. >>LISTING 


[ CDF >>LISTING Directive Syntax 


>>LISTING {ON} 
CC ee {OFF} 


The directive allows the program listing to be de-(activated). 
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3.13. >>LEAP-SECONDS 


[ CDF >>LEAP-SECONDS Directive Syntax ] 


>>LEAP-SECONDS 


The >>LEAP-SECONDS CDF directive is syntactically recognized but is otherwise 
non-functional. 


Allows for more than 60 seconds per minute. 
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3.14. $ Directives 


[ CDF $ Directive Syntax | 


$ (Dollar) Directives - Active. 
These directives are active and have the same function as ones starting with >>: 


$DEFINE 
$DISPLAY ON|OFF 
$IF 

$ELIF 

$ELSE 

$ELSE-IF 

$END 

$SET 


It is recommended to use the standard directives only instead of the MF 
directives (when possible) as these have a higher chance for being portable. 


$ (Dollar) Directives - Not Active. 
These are NOT active and will produce a warning message: 


$DISPLAY VCS ... 

Recognised but otherwise ignored. 

@OPTIONS options-text 

Additional Micro-Focus directives accepted : 


ADDRSV | ADD-RSV literal-1 

ADDSYN | ADD-SYN literal-1 = literal-2 

ASSIGN "EXTERNAL" | "DYNAMIC" 

BOUND 

CALLFH literal-1 

COMP1 | COMP-1 "BINARY" | "FLOAT" 

FOLDCOPYNAME | FOLD-COPY-NAME AS "UPPER" | "LOWER" 
MAKESYN | MAKE-SYN 

NOBOUND | NO-BOUND 

NOFOLDCOPYNAME | NOFOLD-COPY-NAME | NO-FOLD-COPY-NAME 
OVERRIDE literal-1 = literal-2 

REMOVE literal-1 

SOURCEFORMAT | SOURCE-FORMAT "FIXED" | "FREE" | "VARIABLE" 
SSRANGE "2" 
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NOSSRANGE | NO-SSRANGE 


Offers support for MF Compiler Directives. 
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3.15. Predefined compilation variables 


GnuCOBOL defines compilation variables when various conditions are true. If the condition 
associated with a variable is false, the variable is not defined. 


DEBUG The -d debug flag is specified. 


EXECUTABLE 
Module being compiled contains the main program. 


GCCOMP The size of a COMP item is determined according to the GnuCOBOL scheme 
where for a picture of length: 


1-2 item = 1 byte 
3-4 item = 2 bytes 
5-9 item = 4 bytes 


10 - 18 item = 8 bytes 
GNUCOBOL GnuCOBOL is compiling the source unit. 


HOSTSIGNS 
A signed packed decimal item’s value may be considered NUMERIC if sign = 
X"FY 


IBMCOMP The size of a COMP item is determined according to the IBM scheme, where 
for a PICTURE of length: 


1-4 item = 2 bytes 
5-9 item = 4 bytes 
10-18 item = 8 bytes 
MODULE The element being compiled does not contain the main program. 


NOHOSTSIGNS 
A signed packed decimal item’s value may not be considered NUMERIC if sign = 
Xx "W F " : 

NOIBMCOMP 


The size of a COMP item is not determined according to the IBM scheme. 


NOSTICKY-LINKAGE 
Sticky linkage (linkage section items remaining allocated between invocations) 
is not active. 


NOTRUNC Numeric data items are truncated according to their internal representation. 
P64 Pointers are greater than 32 bits. 


STICKY-LINKAGE 
Sticky linkage (linkage section items remaining allocated between invocations) 
is active. 
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TRUNC 


OCCOMP 


OPENCOBOL 


Numeric data items are truncated according to their PICTURE clauses. 
While still supported, this may well be removed in the future and should not 
be used. See GCCOMP and GNUCOBOL instead: 


The size of a COMP item is determined according to the GnuCOBOL scheme, 
where for a PICTURE of length: 


1-2 item = 1 byte 
3-4 item = 2 bytes 
5-9 item = 4 bytes 


10 - 18 item = 8 bytes 


GnuCOBOL is compiling the source unit. 


End of Chapter 3 — CDF - Compiler Directing Facility 
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4. IDENTIFICATION DIVISION 


IDENTIFICATION DIVISION Syntax 


[{ IDENTIFICATION } DIVISION. ] 


{ PROGRAM-ID. } { program name } . 
fs aa aE } { literal-1 +} [ AS { literal-2 } ] [ Type-clause ] 
{ FUNCTION-ID. } { literal-3 } [ AS literal-4 ] 

Se mre Neng ORs { function-name } . 


DEFAULT ROUNDED MODE IS {AWAY-FROM-ZERO 

SOTA, a ae {NEAREST-AWAY-FROM-ZERO 
{NEAREST-EVEN 
{NEAREST-TOWARDS-ZERO 
{PROHIBITED 
{TOWARDS-GREATER 
{TOWARDS-LESSER 
{TRUNCATION 

ENTRY-CONVENTION IS {COBOL } 

Pig Pe ara fe Bele eS {EXTERN } 

{STDCALL }] 
comment-1. ] 


| om | 
ae Bet Get ee eee ahaa 


mM 


loon] 
na 
SG 
4 
oo 
(os) 
w 


— 
is) 
> 
4 
ci 
Q 
jo) 
< 
'U 
H 
Ct 
ia) 
o 


comment-2. |] 


[ DATE-MODIFIED. comment-3. ] 


[ DATE-WRITTEN. comment-4. ] 


[ INSTALLATION. comment-5. ] 


[ REMARKS. comment-6. |] 


[ SECURITY. comment-7. ] 
The AUTHOR, DATE-COMPILED, DATE-MODIFIED, DATE-WRITTEN, INSTALLATION, REMARKS 
and SECURITY paragraphs are supported by GnuCOBOL only to provide compatibility with 
programs written for the ANS1974 (or earlier) standards. As of the ANS1985 standard, 
these clauses have become obsolete and should not be used in new programs. 
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PROGRAM-ID Type Clause Syntax ] 


IS [ COMMON ] [ INITIAL|RECURSIVE PROGRAM ] 


The identification division provides basic identification of the program by giving it a name 
and optionally defining some high-level characteristics via the eight pre-defined paragraphs 
that may be specified. 


1. The paragraphs shown above may be coded in any sequence. 


2. The reserved words AS, IS and PROGRAM are optional and may be included, or not, at 
the discretion of the programmer. The presence or absence of these words has no effect 
upon the program. 


3. A Type Clause may be coded only when PROGRAM-ID is specified. If one is coded, 
either COMMON, COMMON INITIAL or COMMON RECURSIVE must be specified. 


4. While the actual IDENTIFICATION DIVISION or ID DIVISION header is optional, the 
PROGRAM-ID / FUNCTION-ID paragraphs are not; only one or the other, however, may 
be coded. 


5. The compiler’s -Wobsolete switch will cause the GnuCOBOL compiler to issue warn- 
ings messages if these (or any other obsolete syntax) is used in a program. 


6. If specified, literal-1 must be an actual alphanumeric literal and may not be a figurative 
constant. 


7. The PROGRAM-ID and FUNCTION-ID paragraphs serve to identify the program to the 
external (i.e. operating system) environment. If there is no AS clause present, the 
program-id will serve as that external identification. If there is an AS clause specified, 
that specified literal will serve as the external identification. For the remainder of this 
document, that "external identification" will be referred to as the primary entry-point 
name. 

8. The INITIAL, COMMON and RECURSIVE words are used only within subprograms serving 
as subroutines. Their purposes are as follows: 

A. COMMON should be used only within subprograms that are nested subprograms. A 
nested subprogram declared as COMMON may be called from any nested program in 
the source file being compiled, not just those "above" it in the nesting structure. 

B. The RECURSIVE clause, if any, will cause the compiler to generate different object 
code for the subprogram that will enable it to invoke itself and to properly return 
back to the program that invoked it. 

User-defined functions (i.e. FUNCTION-ID) are always recursive. 

C. The INITIAL clause, if specified, guarantees the subprogram will be in its initial 

(i.e. compiled) state each and every time it is executed, not just the first time. 


End of Chapter 4 — IDENTIFICATION DIVISION 
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5. 


ENVIRONMENT DIVISION 


[ 


ENVIRONMENT DIVISION Syntax 


1 aa § 


Le 


\ eas | 


re 


7) 


aos 


mom 


eam | 


ENVIRONMENT DIVISION. 


SOURCE-COMPUTER. Compilation-Computer-Specification . ] 
OBJECT-COMPUTER. Execution-Computer-Specification . ] 
SPECIAL-NAMES. Program-Configuration-Specification . ] 
REPOSITORY. Function-Specification... . ] 
INPUT-OUTPUT SECTION. ] 


FILE-CONTROL. General-File-Description... . ] 


I-O-CONTROL . File-Buffering Specification... . ] 


This division defines the external computer environment in which the program will be 
operating. This includes defining any files that the program may be . 


e If both optional sections of this division are coded, they must be coded in the sequence 


shown. 

The paragraphs within the sections may be coded in any order. 

These sections consist of a series of specific, pre-defined, paragraphs (SOURCE-COMPUTER 
and OBJECT-COMPUTER, for example), each of which serves a specific purpose. If no code 
is required for the purpose one of the paragraphs serves, the entire paragraph may be 
omitted. 

If any of the paragraphs within one of the sections are coded, the section header itself 
must be coded. 

If none of the paragraphs within one of the sections are coded, the section header itself 
may be omitted. 


If none of the sections within the environment division are coded, the ENVIRONMENT 
DIVISION. header itself may be omitted. 
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5.1. CONFIGURATION SECTION 


[ CONFIGURATION SECTION Syntax 


CONFIGURATION SECTION. 


[ SOURCE-COMPUTER. Compilation-Computer-Specification . ] 


[ OBJECT-COMPUTER. Execution-Computer-Specification . ] 


[ SPECIAL-NAMES. Program-Configuration-Specification . ] 


[ REPOSITORY. Function-Specification... . ] 


This section defines the computer system upon which the program is being compiled and 
executed and also specifies any special environmental configuration or compatibility char- 
acteristics. 
1. The four paragraphs in this section may be specified in any order but if not in this 
order, a warning will be issued. 
2. The configuration section is not allowed in a nested subprogram. A nested program 
inherits the configuration section settings of its parent program. 


3. If none of the features provided by the configuration section are required by a program, 
the entire CONFIGURATION SECTION. header may be omitted from the program. 
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5.1.1. SOURCE-COMPUTER 


SOURCE-COMPUTER Syntax 


SOURCE-COMPUTER. computer-name [ WITH DEBUGGING MODE ] 


This paragraph defines the computer upon which the program is being compiled and pro- 
vides one way in which debugging code embedded within the program may be activated. 


1. 


The reserved word WITH is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. 


This paragraph is not allowed in a nested subprogram. A nested program inherits the 
SOURCE-COMPUTER settings of its parent program. 


The value specified for computer-name is irrelevant, provided it is a valid COBOL word 
that does not match any GnuCOBOL reserved word. The computer-name value may in- 
clude spaces. This need not match the computer-name used with the OBJECT-COMPUTER 
paragraph, if any. 

The DEBUGGING MODE clause, if present, will inform the compiler that debugging lines 
(those with a ‘D’ in column 7 if Fixed Source Mode is in effect, or those prefixed with 
a >>D if Free Source Mode is in effect) — normally treated as comments — are to be 
compiled. 


Even without the DEBUGGING MODE clause, it is still possible to compile debugging lines. 
Debugging lines may also be compiled by specifying the -fdebugging-line switch 
to the GnuCOBOL compiler. 
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5.1.2. OBJECT-COMPUTER 


OBJECT-COMPUTER Syntax 


OBJECT-COMPUTER. [ computer-name ] 


[ CHARACTER CLASSIFICATION IS { locale-name-1 


| 
Cea age { LOCALE } 
yeas t 
{ USER-DEFAULT  } 
t 
t 


{ SYSTEM-DEFAULT 


The MEMORY SIZE and SEGMENT-LIMIT clauses are syntactically recognized but are other- 
wise non-functional. 


This paragraph describes the computer upon which the program will execute. 


The computer-name, if specified, must immediately follow the OBJECT-COMPUTER para- 
graph name. The remaining clauses may be coded in any sequence. 


The reserved words CHARACTER, IS, PROGRAM and SEQUENCE are optional and may be 
omitted. The presence or absence of these words has no effect on the program. 


The value specified for computer-name, if any, is irrelevant provided it is a valid COBOL 
word that does not match any GnuCOBOL reserved word. The computer-name may in- 
clude spaces. This need not match the computer-name used with the SOURCE-COMPUTER 
paragraph, if any. 

The OBJECT-COMPUTER paragraph is not allowed in a nested subprogram. A nested 
program inherits the OBJECT-COMPUTER settings of its parent program. 


The COLLATING SEQUENCE clause allows you to specify a customized character collating 
sequence to be used when alphanumeric values are compared to one another. Data will 
still be stored in the character set native to the computer, but the logical sequence in 
which characters are ordered for comparison purposes can be altered from that defined 
by the computer’s native character set. The alphabet-name-1 you specify needs to be 
defined in the SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) paragraph. 


If no COLLATING SEQUENCE clause is specified, the collating sequence implied by the 
character set native to the computer (usually ASCII) will be used. 
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7. The optional CLASSIFICATION clause may be used to specify a locale for the 
environment in which the program will execute, for the purpose of influencing 
the upper-case and lower-case mappings of characters for the UPPER-CASE (see 
[UPPER-CASE], page 525) and LOWER-CASE (see [LOWER-CASE], page 473) intrinsic 
functions and the classification of characters for the ALPHABETIC, ALPHABETIC-LOWER 
and ALPHABETIC-UPPER class tests. The definitions of these classes is taken from the 
cultural convention specification (LC_CTYPE) from the specified locale. 


The meanings of the four locale specifications are as follows: 


A. 
B. 


C. 


D. 


locale-name-1 references a LOCALE (see [SPECIAL-NAMES], page 92) definition. 
The keyword LOCALE refers to the current locale (in effect at the time the program 
is executed) 

The keyword USER-DEFAULT references the default locale specified for the user 
currently executing this program. 


The keyword SYSTEM-DEFAULT denotes the default locale specified for the computer 
upon which the program is executing. 


8. Absence of a CLASSIFICATION clause will cause character classification to occur ac- 
cording to the rules for the computer’s native character set (ASCII, EBCDIC, etc.). 
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5.1.3. SPECIAL-NAMES 


SPECIAL-NAMES Syntax 


SPECIAL-NAMES. 


{ CONSOLE IS CRT ] 


[ CRT STATUS IS identifier-1 ] 


[ device-name-1 IS mnemonic-name-2 ]... 
[ feature-name-1 IS mnemonic-name-3 ]... 
[ Alphabet-Clause ]... 


[ Class-Definition-Clause ]... 


‘ome | 


Switch-Definition-Clause ]... 


— 


Symbolic-Characters-Clause ]... 


The EVENT STATUS and SCREEN CONTROL clauses are syntactically recognized but are oth- 
erwise non-functional. 


Alphabet-Name-Clause, Class-Definition-Clause, 
Switch-Definition-Clause and Symbolic-Characters-Clause 
are discussed in detail in the next four sections. 
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The SPECIAL-NAMES paragraph provides a means for specifying various program and 


operating environment configuration options. 


1. 


10. 


11. 


12. 


15 


The various clauses that may be specified within the SPECIAL-NAMES paragraph may 
be coded in any order. 


The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 

The SPECIAL-NAMES paragraph is not allowed in a nested subprogram. A nested pro- 
gram inherits the SPECIAL-NAMES settings of its parent program. 

Only the final clause specified within this paragraph should be terminated with a 
period. 

The CALL-CONVENTION clause allows a decimal integer, representing a series of 
ON/OFF switch settings, to be associated with a mnemonic name which may then be 
coded on a CALL statement (see [CALL], page 293). The switch settings defined by 
this mnemonic will then control how the linkage to a subroutine invoked by the CALL 
statement that references mnemonic-name-1 will be handled. 


The CONSOLE IS CRT clause, if specified, will cause a DISPLAY statement lacking an 
explicit UPON clause to be treated as a DISPLAY data-item statement (see [DISPLAY 
data-item], page 311), and any ACCEPT statement lacking a FROM clause to be treated 
as a ACCEPT data-item statement (see [ACCEPT data-item], page 272). 

If the CRT STATUS clause is not specified, an implicit COB-CRT-STATUS identifier (with a 
PICTURE 9(4)) will be allocated for the purpose of receiving screen ACCEPT statuses. If 
CRT STATUS is specified, then identifier-1 must be defined in the program as a PICTURE 
9(4) field. 

The CURRENCY SIGN clause may be used to redefine the character to be used as a 
currency sign in a PICTURE (see [PICTURE], page 194) clause. The default currency 
sign is a dollar-sign (‘$’). You may specify any character except 0-9, A-Z, a-z, +, -, 5, 
., *, /, 3, ©), =, \\, quote (‘"’) or space. 

The CURSOR IS clause allows you to specify a 4- or 6-character data item into which 
the cursor screen location at the time a screen ACCEPT is satisfied. The value will be 
returned as rrcc or rrrcecc, depending upon the length of the specified identifier-2, where 
rr and rrr represent the row number (starting at zero) and cc and ccc represent the 
column number (also starting at zero). There is no default data item allocated for this 
data if the CURSOR IS clause is not specified, and it is the programmer’s responsibility 
to define identifier-2 if the clause is specified. 

The DECIMAL POINT IS COMMA clause reverses the definition of the ‘,’ and ‘.’ characters 
when they are used as PICTURE editing symbols and within numeric literals. This can 
have unwanted side-effects - see [Punctuation], page 37. 

The LOCALE clause may be used to associate external OS-defined locale names (literal- 
2) with an internal name (locale-name-1) that may then be referenced within the 
program. Locale names are defined by the Operating System and/or C compiler Gnu- 
COBOL will be utilizing on your computer. 

The following is the list of possible locale codes, for example, that would be available 
on a Windows computer running a GnuCOBOL version that was built utilizing the 
MinGW Unix-emulator and the GNU C compiler (gcc): 
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A af_ZA, am_ET, ar_AE, ar_BH, ar_DZ, ar_EG, ar_IQ, ar_JO, ar_KW, 
ar_LB, ar_LY, ar_MA, ar_OM, ar_QA, ar_SA, ar_SY, ar_TN, ar_YE, 
arn_CL, as_IN, az_Cyrl_AZ, az_Latn_AZ 


B ba_R, be-BY, bg_-BG, bn_IN bo_BT, bo_CN, br_FR, bs_Cyrl_BA, 
bs_Latn_BA 

C ca_ES, cs_CZ, cy_GB 

D da_DK, de_AT, de_CH, de_DE, de_LI, de_LU, dsb_DE, dv_MV 

E el_GR, en_029, en_AU, en_BZ, en_CA, en_GB, en_IE, en_IN, en_JM, 


en_MY en_NZ, en_PH, en_SG, en_TT, en_US, en_ZA, en_ZW, es_AR, 
es_BO, es_CL, es_CO, es_CR, es_DO, es_EC, es_ES, es_GT, es_HN, 
es_MX, es_NI, es_PA, es_PE, es_PR, es_PY, es_SV, es_US, es_UY es_VE, 
et_EE, eu_ES 


fa_IR, fi_FI, fil.PH, fo_FO, fr_BE, fr-CA, fr_CH, fr_FR, fr-LU, fr_MC, 
fy_NL 


ga_IE, gbz_AF, gl_ES, gsw_FR, gu_IN 

ha_Latn_NG, he_IL, hi_IN, hr_BA, hr_HR, hu_HU, hy_AM 

id_ID, ig_NG, ii_CN, is_IS, it_CH, it_IT, iu_Cans_CA, iu_Latn_CA 
ja_JP 

ka_GE, kh_KH, kk_KZ, kl_-GL, kn_IN, ko_KR, kok_IN, ky_KG 
Ib_LU, lo_LA, It_LT, Iv_LV 


mi_NZ, mk_MK, ml_IN, mn_Cyrl.MN, mn_Mong_CN moh_CA, mr_IN, 
ms_BN, ms_MY, mt_MT 


nb_NO, ne_NP, nl_BE, nl_-NL, nn_NO, ns_ZA 
oc_FR, or_IN 

pa_IN, pl_PL, ps_AF, pt_BR, pt_PT 
qut_GT, quz_BO, quz_EC, quz_PE 

rm_CH, ro_RO, ru_RU, rw_RW 


sa_IN, sah_RU, se_FI, se.NO se_SE, si_LK, sk_SK, sl_SI, sma_NO, 
sma_SE, smj-NO, smj_SE, smn_FI, sms_FI, sq AL, sr_Cyrl_BA, 
sr_Cyrl_CS, sr_Latn_BA, sr_Latn_CS, sv_FI, sv_SE, sw_KE syr_SY 


ta_IN, te_IN, tg_Cyrl_TJ, th_TH tk._TM, tmz_Latn_DZ, tn_ZA, tr_IN, 
tr_TR, tt_RU 


ug_CN, uk_UA, ur_PK, uz_Cyrl_UZ, uz_Latn_UZ 
vi_VN 

wen_DE, wo_SN 

xh_ZA 


rej 


genus mo 


a nwAowvo az 


xade 
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13. 


14. 


15. 


YY: yo_NG 


Z zh_CN, zh_HK, zh_MO, zh_SG, zh_TW, zu_ZA 

The NUMERIC SIGN TRAILING SEPARATE specification causes all signed numeric USAGE 
DISPLAY data items to be created as if the SIGN IS TRAILING SEPARATE CHARACTER 
clause was included in their definitions. 

The device-name-1 IS mnemonic-name-2 clause allows you to specify an alternate 
name (device-name-1) for one of the built-in GnuCOBOL device name mnemonic- 
name-2. The list of device names built-into GnuCOBOL, and the physical device 
associated with that name, are as follows: 


CONSOLE ‘This is the (screen-mode) display of the PC or Unix system. 


STDIN 

SYSIN 

SYSIPT These devices (they are all synonymous) represent standard system input 
(pipe 0). On a PC or UNIX system, this is typically the keyboard. The 
contents of a file may be delivered to a GnuCOBOL program for access 
via one of these device names by adding the sequence ‘O< filename’ to the 
end of the programs execution command. 

PRINTER 

STDOUT 

SYSLIST 

SYSLST 


SYSOUT These devices (they are all synonymous) represent standard system output 
(pipe 1). On a PC or UNIX system, this is typically the display. Output 
sent to one of these devices by a GnuCOBOL program can be sent to a file 
by adding the sequence ‘1> filename’ to the end of the programs execution 
command. 


STDERR 

SYSERR These devices (they are synonymous) represent standard system error out- 
put (pipe 2). On a PC or UNIX system, this is typically the display. 
Output sent to one of these devices by a GnuCOBOL program can be sent 
to a file by adding the sequence ‘2> filename’ to the end of the programs 
execution command. 

The feature-name-1 IS mnemonic-name-3 clause allow for mnemonic names to be 

assigned to up to the 13 printer channel (i.e. vertical page positioning) position feature 

names Cnn (nn=01-12) and CSP. Once a channel position has been assigned a mnemonic 

name, statements of the form WRITE record-name AFTER ADVANCING mnemonic-name- 

3 may be coded to write the specified print record at the channel position assigned to 

mnemonic-name-3. 

Printers supporting channel positioning are generally mainframe-type line printers. 

When writing to printers that do not support channel positioning, a formfeed will be 

issued to the printer. 

The CSP positioning option stands for “No Spacing”. Testing on a MinGW build of 

GnuCOBOL shows that this too results in a formfeed being issued. 
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5.1.3.1. Alphabet-Name-Clause 


SPECIAL-NAMES Alphabet-Clause Syntax 


ALPHABET alphabet-name-1 IS { ASCII 


A 

zg 

2 

2g 

z 

2g 

2g 
PES YY YY YY 


{ Literal-Clause... 


SPECIAL-NAMES ALPHABET Literal-Clause Syntax 


literal-1 [ { THRU|THROUGH literal-2 } ] 


sae i } 
{ {ALSO literal-3}... } 


The ALPHABET clause relates alphabet-name-1 to a specified character code set or collating 
sequence, including one you define yourself using the literal-1 option. 


1. 


GE ite ASR abe 


The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 

The reserved words THRU and THROUGH are interchangeable. 

GnuCOBOL considers ASCII, STANDARD-1 and STANDARD-2 to be interchangeable. 
NATIVE specifies the system default character set. 

The following points apply to using the literal-n specifications to compose a custom 
character set: 


A. The literal-n values are either integers or alphanumeric quoted characters. These 
represent a single character in the NATIVE character set, either by its actual text 
value (alphanumeric quoted character) or by ordinal position in the NATIVE char- 
acter set (integer), 


B. The sequence in which characters are defined in this clause specifies the relative 
order those characters should have when comparisons are made using this alphabet. 


C. Character positions in this list do not affect the actual binary storage values used 
for the characters. Binary values will still be those of the NATIVE character set. 
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D. You may specify any of the figurative constants SPACE, SPACES, ZERO, ZEROS, 
ZEROES, QUOTE, QUOTES, HIGH-VALUE, HIGH-VALUES, LOW-VALUE or LOW-VALUES 
for any of the literal-1, literal-2 or literal-3 specifications. 

6. Once you have defined an alphabet name, that alphabet name may be used on specifi- 
cations in CODE-SET, COLLATING SEQUENCE, or SYMBOLIC CHARACTERS clauses elsewhere 
in the program. 
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5.1.3.2. Class-Definition-Clause 


( SPECIAL-NAMES Class-Definition-Clause Syntax 


CLASS class-name-1 IS { literal-1 [ THRU|THROUGH literal-2 ] }... 


1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. The reserved words THRU and THROUGH are interchangeable. 

3. Both literal-1 and literal-2 must be alphanumeric literals of length 1. 

4. The literal(s) specified on this clause define the possible characters that may be found 
in a data item’s value in order to be considered part of the class. 

5. For example, the following defines a class called Hexadecimal, the definition of which 
specifies the only characters that may be present in an alphanumeric data item if that 
data item is to be part of the Hexadecimal class: 

CLASS Hexadecimal IS ’0’ THRU ’9’ 
>A?) THRU ’?F? 
2a? THRU ’f’ 

6. Once class Hexadecimal has been defined, program code could then use a statement 
such as IF input-item IS Hexadecimal to determine if the value of characters in a 
data item are valid according to that class. 
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5.1.3.3. Switch-Definition-Clause 


[ 


SPECIAL-NAMES Switch-Definition-Clause Syntax 


switch-name-1 [ IS mnemonic-name-1 ] 


[ ON STATUS IS condition-name-1 ] 


[ OFF STATUS IS condition-name-2 ] 


The switch-definition clause associates a condition-name with a run-time execution switch 
so that the status of that switch may be tested from within a program. 


1. 


The reserved words IS and STATUS are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. The valid switch-name-1 names are SWITCH-n (n = 0-36). 


3. If the program is compiled with the -fsyntax-extension switch, the switch names 


SWn (n = 0-15) are also valid; they correspond to SWITCH-0 through SWITCH-15, 
respectively as well as SWITCH-16 through SWITCH-36, SWITCH 0 through SWITCH 26 
and SWITCH A through SWITCH Z. 


At execution time, each switch will be associated with a COB_SWITCH_n run-time 
environment variable, where n will have the value ‘0’ through ‘15’. Any of these sixteen 
environment variables that have the value ON (regardless of upper- or lower-case value) 
will be considered to be set “on”. Any of these sixteen environment variables having 
no value at all or a value other than ON will be considered OFF. 


Each specified switch must have at least one of a IS mnemonic-name-1, ON STATUS or 
an OFF STATUS option defined for it, otherwise there will be no way to reference the 
switch from within a GnuCOBOL program. 

The IS mnemonic-name-1 syntax provides a means for setting the switch to either an 
ON or OFF value via the SET statement (see [SET], page 382). 

The ON STATUS and OFF STATUS syntax provides a way of associating a condition-name 
with either the on or off status of the switch, so that status may be tested at execution 
time via the IF statement (see [IF], page 338). 
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5.1.3.4. Symbolic-Characters-Clause 


SPECIAL-NAMES-Symbolic-Characters-Clause Syntax 


SYMBOLIC CHARACTERS 


{ symbolic-character-1... IS|ARE integer-1... }... 


{[ IN alphabet-name-1 ] 


This clause may be used to define your own figurative constants. 


1. 


The reserved words ARE, CHARACTERS and IS are optional and may be omitted. The 
presence or absence of these words has no effect upon the program. 


There must be exactly as many integer-1 values specified as there are 
symbolic-character-1 names. 

Each symbolic character name will be associated with the corresponding integer-1‘" 
character in the alphabet named in the IN clause. The integer values are selecting 
characters from the alphabet by their ordinal position and not by their numeric value; 
thus, an integer of 15 will select the 15*" character in the specified alphabet, regardless 
of the actual numeric value of the bit pattern that constitutes that character. 


4. If no alphabet-name-1 is specified, the systems native character set will be assumed. 


The following two code examples define the same set of figurative constant names for 
five ASCII control characters (assuming that ASCII is the system’s native character 
set). The two examples are identical in their effects, even though the way the figurative 
constants are defined is different. 


Individually 
SYMBOLIC CHARACTERS NUL IS 1 
SOH IS 2 
BEL IS 8 
Dc1i IS 18 
Dc2 IS 19 
Respectively 


SYMBOLIC CHARACTERS NUL SOH BEL DC1i DC2 
ARE 1 2 8 18 19 
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5.1.4. REPOSITORY 


{ intrinsic-function-name-2 INTRINSIC 


REPOSITORY Syntax ] 
REPOSITORY. 
FUNCTION { function-prototype-name-1 [ AS literal-1] }... 
Peat SEG { oe s 
{ intrinsic-function-name-1 [ AS literal-2 ] } 
{ a } 
} 
z 


{ATT TNTRINGIO: °° |. Cee ee 


The REPOSITORY paragraph provides a way to control access to the various built-in 
intrinsic functions and any user defined functions that your program will be using. 


1. 


The REPOSITORY paragraph is not allowed in a nested subprogram. A nested program 
inherits the REPOSITORY settings of its parent program. 


The INTRINSIC clause allows you to flag one or more (or ALL) built-in intrinsic 
functions as being usable without the need to code the keyword FUNCTION in front of 
the function names. 


As an alternative to using the ALL INTRINSIC clause, you may instead compile your 
GnuCOBOL programs using the -fintrinsics=ALL switch. 


The function-prototype-name-1 option is required to specify the name of a user-defined 
function your program will be using. Optionally, should you desire, you may specify 
an alias name by which you will reference that user-defined function. Should you wish, 
you may also use the AS clause to provide an alias name for a built-in intrinsic function. 


The following example 


e enables all intrinsic functions to be specified without the use of the FUNCTION 
keyword, 


e names two user-defined functions named MY-FUNCTION-1 and MY-FUNCTION-2 that 
will be used by the program and 


e specifies the alias names SIGMA for the intrinsic function STANDARD-DEVIATION and 
MF2 for MY-FUNCTION-2. 


REPOSITORY. 
FUNCTION ALL INTRINSIC 
FUNCTION MY-FUNCTION-1 
FUNCTION MY-FUNCTION-2 AS "MF2" 
FUNCTION STANDARD-DEVIATION AS "SIGMA". 


A special note about user-defined functions — because you must name a user-defined 


function that your program will be using in the REPOSITORY paragraph, you may always 
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reference that function from your program’s procedure division without needing to use the 
FUNCTION keyword. 
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5.2. INPUT-OUTPUT SECTION 


f INPUT-OUTPUT SECTION Syntax 


[ INPUT-OUTPUT SECTION. ] 


{ SELECT-Statement... ] 
[ I-O-CONTROL. ] 


[ MULTIPLE-FILE-Statement ] 


{ SAME-RECORD-Statement ] 


The INPUT-OUTPUT section provides for the definition of any files the program will be 
accessing as well as control of the I/O buffering process against those files through the 
FILE-CONTROL and I-O-CONTROL paragraphs, respectively. 

1. As the diagram shows, there are three types of statements that may occur in the 
two paragraphs of this section. If none of the statements are coded in a particular 
paragraph, the paragraph itself may be omitted, otherwise it is required. 

2. If neither paragraph is coded, the INPUT-OUTPUT SECTION. header itself may be omit- 
ted, otherwise it is normally required. 

3. If the compiler configuration file (see [Compiler Configuration Files], page 645) you are 
using has relaxed-syntax-check set to ‘yes’, the FILE-CONTROL and I-O-CONTROL 
paragraphs may be specified without the INPUT-OUTPUT SECTION header having been 
coded. 

4. If both statement types are coded in the I-O-CONTROL paragraph, the order in which 
those statements are coded is irrelevant. 


15 January 2023 Chapter 5 - ENVIRONMENT DIVISION 


104 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


5.2.1. SELECT 


SELECT Statement Syntax } 


SELECT [ [ NOT ] OPTIONAL ] file-name-1 


[ ASSIGN { TO } [{ EXTERNAL }] [{ DISC|DISK +] [{ identifier-1 }] ] 
ones Ar USING Seeger es aS ae Ce ee +} =6©{ word-1 } 
{ DYNAMIC } { DISPLAY } )=6 { literal-1 } 
eye ei ene } 
{ KEYBOARD } 
ee Rs } 
{ LINE ADVANCING } 
saa ald ae a } 
{ PRINTER } 
s Maasarae eae } 
{ RANDOM } 
{AERA } 
{ TAPE } 
[ COLLATING SEQUENCE IS alphabet-name-1 ] 
[ FILE|SORT ] STATUS IS identifier-2 [ identifier-3 ] ] 
[ LOCK MODE IS { MANUAL| AUTOMATIC +] 
aan EE ee ER } 
{ EXCLUSIVE [ WITH { LOCK ON MULTIPLE RECORDS } ] } 
ears Ae my eee a eRe lave hh ge ge 
{ LOCK ON RECORD } 
dite eto oe etait } 
{ ROLLBACK } 
7 naa aes } 
[ ORGANIZATION Clause ] 
[ ORGANISATION Clause ] 
[ RECORD DELIMITER IS STANDARD-1 ] 
[ RESERVE integer-1 AREAS ] 
[ SHARING WITH { ALL OTHER } ] 
sa a te gr } 
{ NO OTHER } 
; ae } 


{ READ ONLY } 
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The COLLATING SEQUENCE, RECORD DELIMITER, RESERVE and ALL OTHER clauses are syn- 
tactically recognized but are otherwise non-functional. 


The SELECT statement creates a definition of a file and links that COBOL definition to 
the external operating system environment. 

1. The reserved words AREAS, IS, MODE, OTHER, SEQUENCE, TO, USING and WITH are optional 
and may be omitted. The presence or absence of these words has no effect upon the 
program. 

2. After file-name-1, the various clauses may be coded in any sequence. 

3. A period must follow the last coded clause. 

4. The OPTIONAL clause, to be used only for files that will be used to provide input 
data to the program, indicates the file may or may not actually be available at run- 
time. Attempts to OPEN an OPTIONAL file when the file does not exist will receive a 
special non-fatal file status value (see status 05 in the list of file status values below) 
indicating the file is not available; a subsequent attempt to READ that file will return 
an AT END (end-of-file) condition. Optionally, files may be designated as NOT OPTIONAL, 
if desired. This is useful when specifying the compiler’s -foptional-file switch, 
which automatically makes all files OPTIONAL except for those explicitly declared as 
NOT OPTIONAL. 

5. The file-name-1 value that you specify will be the name by which you will reference 
the file within your program. This name should be formed according to the rules for 
user-defined names (see [User-Defined Words], page 10). 

6. The optional ASSIGN clause specifies how — at runtime, when file-name-1 is opened 
— either a logical device (STDIN, STDOUT) or a file anywhere in one of the currently- 
mounted file systems will be associated with file-name-1, as follows: 


A. There are three components to the ASSIGN clause: 
Type EXTERNAL, DYNAMIC or neither 
Device the list of device choices 


Locator — shown as a choice between identifier-1, word-1 and literal-1. 

B. ASSIGN TO DISC file-name-1 will be assumed if there is no ASSIGN clause on a 
SELECT. 

C. If an ASSIGN clause is coded without a Device, the device DISC will be assumed. 


D. Ifa Locator clause is coded, the COBOL file file-name-1 will be attached to a data 
file within any file system that is mounted and available to the executing program 
at the time file-name-1 is opened. How that file is identified varies, depending 
upon the specified Locator, as follows: 

a. If literal-1 is coded, the value of the literal will serve as the File Location 
String that will identify the data file. 

b. If identifier-1 is coded, the value of the identifier will serve as the File Location 
String that will identify the data file. 
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c. If word-1 (a syntactically valid word not duplicating a reserved or user-defined 
word) is coded, and a Type is EXTERNAL, then word-1 itself will serve as the 
File Location String that will identify the data file. If, however, a Type of 
EXTERNAL was not specified, the compiler will create a PIC X(1024) data item 
named word-1 within the program; the contents of that data item at the time 
the program opens file-name-1 will then serve as the File Location String that 
will identify the data file. 


d. File Location Strings will be discussed shortly. 


E. If no Locator is coded, file-name-1 will be attached to a logical device or a file 


based upon the specified (or implied) Device, as follows: 

a. DISC or DISK will assume an attachment to a file named file-name-1 in what- 
ever directory is current at the time the file is opened. 

b. DISPLAY will assume an attachment to the STDOUT logical device; these files 
should only be used for output. 

c. KEYBOARD will assume an attachment to the STDIN logical device; these files 
should only be used for input. 

d. PRINTER will assume an attachment to the LPT1 logical device/port; these files 
should only be used for output. 

e. RANDOM or TAPE will behave exactly as DISC does. These two additional De- 
vices are provided to facilitate the compilation of COBOL source from other 
COBOL implementations. 


. The LINE ADVANCING device requires that a Locator be specified; these files should 


only be used for output. A COBOL Line Advancing file will allow carriage-control 
characters such as line-feeds and form-feeds to be written to the attached operat- 
ing system file, via the ADVANCING clause of the WRITE statement (see [WRITE], 
page 417). 


. File Location Strings are used (at runtime) to identify the path and filename to 


the data file that must be attached to file-name-1 when that file is opened. 


. If the compiler configuration file (see [Compiler Configuration Files], page 645) 


you used to compile the program with had a filename-mapping value of yes, 
the GnuCOBOL runtime system will first attempt to identify a currently-defined 
environment variable whose value will serve as the data file’s path and filename, 
as follows: 

a. Ifthe compiler configuration file (see [Compiler Configuration Files], page 645) 
(see [Compiler Configuration Files], page 645) you used to compile the pro- 
gram specified mf as the assign-clause value, then the File Locator String 
will be interpreted according to Microfocus COBOL rules — namely, every- 
thing before the last ‘-’ in the File Locator String will be ignored; the char- 
acters after the last ‘-’ will be treated as the base of an environment variable 
name. If there is no ‘-’ character in the File Locator String then the entire 
File Locator String will serve as the base of an environment variable name. 
This is the default behaviour for every config file except ibm. 

b. If, on the other hand, the compiler configuration file (see [Compiler Configu- 
ration Files], page 645) you used to compile the program specified mf as the 
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I. 


assign-clause value, then the File Locator String will be interpreted accord- 
ing to according to IBM COBOL rules — namely, the File Locator String is 
expected to be of the form S-xxx or AS-xxx, in which case the xxx will be 
treated as the base of an environment variable name. If there is no ‘-’ char- 
acter in the File Locator String then the entire File Locator String will serve 
as the base of an environment variable name. 


c. Once an environment variable name base (let’s refer to it as bbbb) has been 
determined, the runtime system will look for the first one of the following 
environment variables that exists, in this sequence: 


DD_bbbb 
dd_bbbb 
bbbb 


Windows systems are case-insensitive with regard to environment variables, 
so there is no difference between the first two when using a GnuCOBOL 
implementation built for either Windows/MinGW or native Windows. 


If an environment variable was found, its value will serve as the path and 
filename to the data file. 


If no environment variable was found, or the configuration file (see [Compiler Con- 
figuration Files], page 645) used to compile the program had a filename-mapping 
value of NO, then the File Locator String value will serve as the path and filename 
to the data file. 


Paths and file names may be specified on an absolute (C:\\Data\\datafile.dat, 
/Data/datafile.dat, ...) or relative to the current directory 
(Data\\datafile.dat, Data/datafile.dat, ...) basis. If no directory 
name is included (datafile.dat), the file must be in the current directory. 


7. The FILE STATUS or SORT STATUS clause (they are both equivalent and only one or 
the other, if any, should be specified) is used to specify the name of a two-digit numeric 
data item into which an I/O status code will be saved after every I/O verb that is 
executed against the file. This does not actually allocate the data item — you must 
define the item yourself somewhere in the data division. Note that the following list is 
not definitive: more can be added and any tests should include one for non zeros as a 
catch all. Possible status codes that can be returned to a FILE STATUS data item are 


as follows: 

00 Success 

02 Success (Duplicate Record Key Written) 

04 Success (Incomplete) 

05 Success (Optional File Not Found) 

07 Success (No Unit) 

10 End of file reached if reading forward or beginning-of-file reached if reading 
backward 

14 Out of key range 
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21 Key invalid 

22 Key already exists 

23 Key not found 

24 Key boundary violation 

30 Permanent I/O error 

31 Inconsistent filename 

34 Boundary violation 

35 File not found 

37 Permission denied 

38 Closed with lock 

39 Conflicting attribute 

41 File already open 

42 File not open 

43 Read not done 

44 Record overflow 

46 Read error 

47 OPEN INPUT denied (insufficient permissions to read file) 
48 OPEN OUTPUT denied (insufficient permissions to write to file) 
49 OPEN I-0 denied (insufficient permissions to read and/or write file) 
51 Record locked 

52 End of page 

57 LINAGE bad specification (I-O linage) 

61 File sharing failure 

71 Bad character 

91 File not available 


8. The SHARING clause defines the conditions under which the program will be willing (or 
not) to allow other programs executing at the same time to access the file. See [File 
Sharing], page 57, for the details. 


9. The LOCK clause defines how concurrent access to the file will be managed on a record- 
by-record basis. See [Record Locking], page 59, for the details. 


10. For syntax details for the ORGANIZATION clause, see next group of paragraphs. 


11. A SELECT statement without an ORGANIZATION explicitly coded will be handled as if 
the folowing ORGANIZATION clause had been specified: 


ORGANIZATION IS SEQUENTIAL 
ACCESS MODE IS SEQUENTIAL 
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5.2.1.1. ORGANIZATION SEQUENTIAL 


ORGANIZATION SEQUENTIAL Clause Syntax 


[ ORGANIZATION|ORGANISATION IS ] RECORD BINARY SEQUENTIAL 


Files declared as ORGANIZATION SEQUENTIAL will consist of records with no explicit end-of- 
record delimiter character sequences; records in such files are “delineated” by a calculated 
byte-offset (based on the maximum record length) into the file. 


1. 


The reserved words BINARY, IS, MODE and RECORD are optional and may be omitted. 
The presence or absence of these words has no effect upon the program. 


The reserved words ORGANIZATION and ORGANISATION are interchangeable. 


3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) 


is optional to provide compatibility with those (few) COBOL implementations that 
consider ORGANIZATION to be optional. Most COBOL implementations do require the 
word ORGANIZATION, so it should be used in new programs. 


These files cannot be prepared with any standard text-editing or word processing soft- 
ware as all such programs will embed delimiter characters at the end of records (use 
ORGANIZATION IS LINE SEQUENTIAL instead). 


These files may contain either USAGE DISPLAY or USAGE COMPUTATIONAL (of any variety) 
data since no binary data sequence can be accidentally interpreted as an end-of-record 
delimiter. 


While records in a ORGANIZATION SEQUENTIAL file may be defined as having variable- 
length records, the file will be structured in such a manner as to reserve space for each 
record equal to the size of the largest possible record, based on the file’s description in 
the FILE SECTION. 


The ACCESS MODE SEQUENTIAL clause is optional because, if absent, it will be assumed 
anyway for this type of file. The internal structure of these files is such that they can 
only be processed in a sequential manner; in order to read the 100th record in such a 
file, for example, you first must read records 1 through 99. 


Sequential files are processed using the following statements: 
e CLOSE (see [CLOSE], page 299) 
e COMMIT (see [COMMIT], page 300) 
e DELETE (see [DELETE], page 304) 
e MERGE (see [MERGE], page 349) 
e OPEN (see [OPEN], page 358) 
e READ (see [READ], page 366) 
e REWRITE (see [REWRITE], page 374) 
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e SORT (see [SORT], page 391) 
e UNLOCK (see [UNLOCK], page 412) 
e WRITE (see [WRITE], page 417) 
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5.2.1.2. ORGANIZATION LINE SEQUENTIAL 


ORGANIZATION LINE SEQUENTIAL Clause Syntax 


[ ORGANIZATION|ORGANISATION IS ] LINE SEQUENTIAL 


[ PADDING CHARACTER IS literal-1 | identifier-1 ] 


The PADDING CHARACTER clause is syntactically recognized but is otherwise non-functional. 


Files declared as ORGANIZATION LINE SEQUENTIAL will consist of records terminated by 


an end-of-record delimiter character or character sequence. 


1. 


The reserved words CHARACTER, IS and MODE are optional and may be omitted. The 
presence or absence of these words has no effect upon the program. 


2. The reserved words ORGANIZATION and ORGANISATION are interchangeable. 
3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) 


is optional to provide compatibility with those (few) COBOL implementations that 
consider that word to be optional. Most COBOL implementations do require the word 
ORGANIZATION, so it should be used in new programs. 


4. This is the only ORGANIZATION valid for files that are assigned to the PRINTER device. 


5. These files may be created with any standard text-editing or word processing software 


capable of writing text files. Such files should not contain any USAGE COMPUTATIONAL or 
BINARY (of any variety) data since such fields could accidentally contain byte sequences 
that could be interpreted as an end-of-record delimiter. 


6. Both fixed- and variable-length record formats are supported. 


7. The end-of-record delimiter sequence will be X‘0A’ (an ASCII line-feed character) or a 


10. 


X‘ODOA’ (an ASCII carriage-return + line-feed sequence). The former is used on Unix 
implementations of GnuCOBOL (including Windows/MinGW, Windows/Cygwin and 
OSX implementations) while the latter would be used with native Windows implemen- 
tations. 


When reading a LINE SEQUENTIAL file, records in excess of the size implied by the file’s 
description in the FILE SECTION will be truncated while records shorter than that size 
will be padded to the right with SPACES. 


The ACCESS MODE SEQUENTIAL clause is optional because, if absent, it will be assumed 
anyway for this type of file. The internal structure of these files is such that the data 
can only be processed in a sequential manner; in order to read the 100th record in such 
a file, for example, you first must read records 1 through 99. 


Files assigned to PRINTER or CONSOLE should be specified as ORGANIZATION LINE 
SEQUENTIAL. 
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11. Line Sequential files are processed using the following statements: 
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CLOSE (see [CLOSE], page 299) 
COMMIT (see [COMMIT], page 300) 
DELETE (see [DELETE], page 304) 
MERGE (see [MERGE], page 349) 
OPEN (see [OPEN], page 358) 

READ (see [READ], page 366) 
REWRITE (see [REWRITE], page 374) 
SORT (see [SORT], page 391) 

UNLOCK (see [UNLOCK], page 412) 
WRITE (see [WRITE], page 417) 
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5.2.1.3. ORGANIZATION RELATIVE 


[ 


ORGANIZATION RELATIVE Clause Syntax 


[ ORGANIZATION|ORGANISATION IS ] RELATIVE 


mii A casas tiga ee pene? of 
{ DYNAMIC } 
Arye cer } 
{ RANDOM } 


These files are files with an internal organization such that records may be processed in a 
sequential manner based upon their physical location in the file or in a random manner by 
allowing records to be read, written or updated by specifying the relative record number in 
the file. 


1. 


The reserved words IS, KEY and MODE are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


2. The reserved words ORGANIZATION and ORGANISATION are interchangeable. 
3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) 


is optional to provide compatibility with those (few) COBOL implementations that 
consider that word to be optional. Most COBOL implementations do require the word 
ORGANIZATION, so it should be used in new programs. 


ORGANIZATION RELATIVE files cannot be assigned to the CONSOLE, DISPLAY, LINE 
ADVANCING or PRINTER devices. 


5. The RELATIVE KEY clause is optional only if ACCESS MODE SEQUENTIAL is specified. 
6. While an ORGANIZATION RELATIVE file may be defined as having variable-length records, 


the file will be structured in such a manner as to reserve space for each record equal 
to the size of the largest possible record as defined by the file’s description in the FILE 
SECTION. 
ACCESS MODE SEQUENTIAL, the default ACCESS MODE if none is specified, indicates that 
the records of the file will be processed in a sequential manner, according to their 
physical sequence in the file. 
ACCESS MODE RANDOM means that records will be processed in random sequence by 
specifying their record number in the file every time the file is read or written. 
ACCESS MODE DYNAMIC indicates the program may switch back and forth between 
SEQUENTIAL and RANDOM mode during execution. The file starts out initially in 
SEQUENTIAL mode when first opened but the program may use the START statement 
(see [START], page 397) to switch between sequential and random access. 
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10. The RELATIVE KEY data item is a numeric data item that cannot be defined as a field 
within records of this file. Its purpose is to return the current relative record number 
of a relative file that is being processed in SEQUENTIAL access mode and to serve as a 
key that specifies the relative record number to be read or written when processing a 
relative file in RANDOM access mode. 


11. Relative files are processed using the following statements: 
e CLOSE (see [CLOSE], page 299) 
e COMMIT (see [COMMIT], page 300) 
© DELETE (see [DELETE], page 304) 
e MERGE (see [MERGE], page 349), ACCESS MODE RANDOM not allowed 
e OPEN (see [OPEN], page 358) 
e READ (see [READ], page 366) 
* REWRITE (see [REWRITE], page 374) 
e SORT (see [SORT], page 391), ACCESS MODE RANDOM not allowed 
e START (see [START], page 397) 
e UNLOCK (see [UNLOCK], page 412) 
e WRITE (see [WRITE], page 417) 
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5.2.1.4. ORGANIZATION INDEXED 


( ORGANIZATION INDEXED Clause Syntax } 


[ ORGANIZATION|ORGANISATION IS ] INDEXED 


Greer a aS a Sa 
{ DYNAMIC } 
die tee a } 
{ RANDOM } 
[ RECORD KEY IS { [ data-name-1 ] 


{ [ record-key-name-1 ] 
[ =|{SOURCE IS} data-name-2 ] ... ] } 


[ ALTERNATE RECORD KEY IS { [ data-name-3 ] 


{ [ record-key-name-2 ] 
[ =|{SOURCE IS} data-name-4 ] ... ] } 


Indexed files, like relative files, may have their records processed in either a sequential or 
random manner. Unlike relative files, however, the actual location of a record in an indexed 
file is calculated automatically based upon the value(s) of one or more alphanumeric fields 
within records of the file. For example, an indexed file containing product data might use 
the product identification code as a record key. This means you may read, write or update 
the A6G4328"" record or the Z8X7723" record directly, based upon the product id value of 
those records! 


1. The reserved words IS, KEY and MODE are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


2. The reserved words ORGANIZATION and ORGANISATION are interchangeable. 


3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) 
is optional to provide compatibility with those (few) COBOL implementations that 
consider that word to be optional. Most COBOL implementations do require the word 
ORGANIZATION, so it should be used in new programs. 
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ORGANIZATION INDEXED files cannot be assigned to CONSOLE, DISPLAY, KEYBOARD, LINE 
ADVANCING or PRINTER. 


ACCESS MODE SEQUENTIAL, the default ACCESS MODE if none is specified, indicates that 
the records of the file will be processed in a sequential manner with respect to the 
values of the RECORD KEY or the ALTERNATE RECORD KEY most-recently referenced on a 
START statement (see [START], page 397). 


ACCESS MODE RANDOM means that records will be processed in random sequence by 
accessing the record with specific record key or alternate record key values. 


ACCESS MODE DYNAMIC allows the file will be processed either in RANDOM or SEQUENTIAL 
mode; the program may switch between the two modes as needed. The START statement 
is used to make the switch between modes. 


The RECORD KEY clause defines the field within the record used to provide the primary 
access to records within the file. No two records in the file will be allowed to have the 
same PRIMARY KEY field value. The SOURCE IS clause is for use with Split Keys. 


The ALTERNATE RECORD KEY clause, if used, defines an additional field within the record 
that provides an alternate means of directly accessing records or an additional field by 
which the file’s contents may be processed sequentially. You have the choice of allowing 
records to have duplicate alternate key values, if necessary. 


There may be multiple ALTERNATE RECORD KEY clauses, each defining an additional 
alternate key for the file. 


Usage of the SUPPRESS WHEN clause is used when Sparse Keys are required which may 
take the form for a literal or spaces or zeroes. 


Indexed files are processed using the following statements: 
e CLOSE (see [CLOSE], page 299) 
e COMMIT (see [COMMIT], page 300) 
e DELETE (see [DELETE], page 304) 
e MERGE (see [MERGE], page 349), ACCESS MODE RANDOM not allowed 
e OPEN (see [OPEN], page 358) 
e READ (see [READ], page 366) 
e REWRITE (see [REWRITE], page 374) 
e SORT (sce [SORT], page 391), ACCESS MODE RANDOM not allowed 
e START (see [START], page 397) 
e UNLOCK (see [UNLOCK], page 412) 
e WRITE (see [WRITE], page 417) 
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5.2.2. SAME RECORD AREA 


I-O-CONTROL SAME AREA Syntax } 
SAME { SORT-MERGE } AREA FOR file-name-1... 
tai eg ee ete y 
{ SORT a 
aa bs 
{ RECORD } 


The SAME SORT-MERGE and SAME SORT clauses are syntactically recognized but are otherwise 
non-functional. 


The SAME RECORD AREA clause allows you to specify that multiple files should share the 
same input and output memory buffers. 


1. The reserved words AREA and FOR are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. This statement must be terminated with a period. 


3. While coding only a single file name (the repeated file-name-1 item) is syntactically 
valid, this statement will have no effect upon the program unless at least two files are 
specified. 


4. The effect of this statement will be to cause the specified files to share the same I/O 
buffer in memory. These buffers can sometimes get quite large, and by having multiple 
files share the same buffer memory you may significantly cut down the amount of 
memory the program is using (thus making “room” for more procedural code or data). 
If you do use this feature, take care to ensure that no more than one of the specified 
files are ever OPEN simultaneously. 
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5.2.3. MULTIPLE FILE 


I-O-CONTROL MULTIPLE FILE Syntax 


MULTIPLE FILE TAPE CONTAINS 


The MULTIPLE FILE TAPE clause is obsolete and is therefore recognized but not functional. 


End of Chapter 5 — ENVIRONMENT DIVISION 
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6. DATA DIVISION 


[ DATA DIVISION Syntax 


DATA DIVISION. 


[ FILE SECTION. 
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ] 
{ { 01-Level-Constant } } 
{ { 78-Level-Constant } } 
{ 01-Level-Constant } 
{ 78-Level-Constant } 
[ WORKING-STORAGE SECTION. 
[ { WORKING-STORAGE-SECTION-Data-Item } ]... ] 
{ 01-Level-Constant } 
{ 78-Level-Constant } 
[ LOCAL-STORAGE SECTION. 
[ { LOCAL-STORAGE-SECTION-Data-Item } ]... ] 
{ 01-Level-Constant } 
{ 78-Level-Constant } 
[ LINKAGE SECTION. 
[ { LINKAGE-SECTION-Data-Item } ]... ] 
{ 01-Level-Constant } 
{ 78-Level-Constant } 
[ REPORT SECTION. 
{ Report-Description [ { Report-Group-Definition } ]... }... ] 
{ { 01-Level-Constant } } 
{ { 78-Level-Constant } } 
{ 01-Level-Constant } 
{ 78-Level-Constant } 
[ SCREEN SECTION. 
[ { SCREEN-SECTION-Data-Item } ]... ] 
{ 01-Level-Constant } 
{ 78-Level-Constant } 


All data used by any COBOL program must be defined in one of the six sections of the 
data division, depending upon the purpose of the data. 
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1. If no data will be described in one of the data division sections, that section header 
may be omitted. 

2. If no data division sections are needed, the DATA DIVISION. header itself may be omit- 
ted. 

3. If more than one section is needed in the data division (a common situation), the 
sections must be coded in the sequence they are presented above. 


6.1. Data Definition Principles 


GnuCOBOL data items, like those of other COBOL implementations, are described in a 
hierarchical manner. This accommodates the fact that data items frequently need to be 
able to be broken up into subordinate items. Take for example, the following logical layout 
of a portion of a data item named Employee: 


Employee 
| & additional data items ... 
Employee-Name Employment-Dates 
| | 
| ] 
Last-Name_ First-Name  Middle-initial From-Date To-Date 


eae eo 


Year Month Day Year Month Day 


The Employee data item consists of two subordinate data items — an Employee-Name 
and an Employment-Dates data item (presumably there would be a lot of others too, but 
we don’t care about them right now). As the diagram shows, each of those data items are, 
in turn, broken down into subordinate data items. This hierarchy of data items can get 
rather deep, and GnuCOBOL, like other COBOL implementations, can handle up to 49 
levels of such hierarchical structures. 


As was presented earlier (see [Structured Data], page 14), a data item that is broken 
down into other data items is referred to as a group item, while one that isn’t broken down 
is called an elementary item. 


COBOL uses the concept of a level number to indicate the level at which a data item 
occurs in a data structure such as the example shown above. When these data items are 
defined, they are all defined together with a number in the range 1-49 specified in front of 
their names. Over the years, a convention has come to exist among COBOL programmers 
that level numbers are always coded as two-digit numbers — they don’t need to be specified 
as two-digit numbers, but every example you see in this document will take that approach! 


The data item at the top, also referred to as a record, always has a level number of 01. 
After that, you may assign level numbers as you wish (01-02-0304. .., 01-05-10-15. .., 
etc.), as long as you follow these simple rules: 

1. Every data item at the same level of a hierarchy diagram such as the one you see here 
(if you were to make one, which you rarely will, if ever, once you get used to this 
concept) must have the same level number. 
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2. Every new level uses a level number that is strictly greater than the one used in the 
parent (next higher) level. 


3. When describing data hierarchies, you may never use a level number greater than 49 
(except for 66, 77, 78 and 88 which have very special meanings (see [Special Data 
Items], page 146). 


So, the definition of these data items in a GnuCOBOL program would go something like 
this: 
01 Employee 
05 Employee-Name 
10 Last-Name 
10 First-Name 
10 Middle-Initial 
05 Employment-Dates 
10 From-Date 
15 Year 
15 Month 
15 Day 
10 To-Date 
15 Year 
15 Month 
15 Day 


The indentation is purely at the discretion of the programmer to make things easier for 
humans to read (the compiler couldn’t care less). Historically, COBOL implementations 
that required Fixed Format Mode source programs required that the 01 level number begin 
in Area A and that everything else begins in Area B. GnuCOBOL only requires that all 
data definition syntax occur in columns 8-72. In Free Format Mode, of course, there aren’t 
even those limitations. 


Did you notice that there are two each of Year, Month and Day data names defined? 
That’s perfectly legal, provided that each can be uniquely qualified so as to be distinct 
from the other. Take for example the Year items. One is defined as part of the From-Date 
data item while the other is defined as part of the To-Date data item. In COBOL, we would 
actually code references to these two data items as either Year OF From-Date and Year OF 
To-Date or Year IN From-Date and Year IN To-Date (COBOL allows either IN or OF to 
be used). Since these references would clarify any confusion to us as to which Year might 
be referenced, the GnuCOBOL compiler won’t be confused either. 


The coding example shown above is incomplete; it only describes the data item names 
and their hierarchical relationships to one other. In addition, any valid data item definitions 
will also need to describe what type of data is to be contained in a data item (Numeric? 
Alphanumeric? Alphabetic?), how much data can be held in the data item and a multitude 
of other characteristics. 


When group items are being defined, subordinate items may be assigned the “name” 
FILLER. There may be any number of FILLER items defined within a group item. A data 
item named FILLER cannot be referenced directly; these items are generally used to specify 
an unused portion of the total storage allocated to a group item. Note that it is possible 
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that the name of the group item itself might be specified as FILLER if there is no need to 
ever refer directly to the group structure itself. 
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6.2. FILE SECTION 


[ FILE SECTION Syntax 


[ FILE SECTION. 


{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ] 
{ { 01-Level-Constant } } 
{ { 78-Level-Constant } } 
{ 01-Level-Constant } 
{ 78-Level-Constant } 


Every file that has been referenced by a SELECT statement (see [SELECT], page 104) must 
also be described in the file section of the data division. 


Files destined for use as sort /merge work files must be described with a Sort /Merge File 
Description (SD) while every other file is described with a File Description (FD). Each of 
these descriptions will almost always be followed with at least one record description. 
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6.2.1. File/Sort-Description 


File/Sort-Description Syntax 


FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ] 


ees} 


DATA { RECORD IS } identifier-1... ] 


ET Eee } 
{ RECORDS ARE } 


om } 


LABEL { RECORD IS  } OMITTEDISTANDARD ] 


—_ 
ct 
H 
1 
Pa 
Q 
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Hi 
n 
hb: 
B 
ct 
@O 

0a 
@O 
| 
w 
H- 
Q, 
(?) 
B 
ct 
H- 
Fh 
H- 
(0) 
fi 
iw) 
Co 
tH 
a 
3 
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[ LINES AT TOP integer-5 | identifier-4 ] 


[ WITH FOOTING AT integer-6 | identifier-5 ] ] 


sae 


RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS } ] 
aaa { oe } 
{ IS VARYING IN SIZE } 
5 eee } 
{ [ FROM [ integer-7 TO ] integer-8 CHARACTERS } 
{ ‘am } 
{ } 


DEPENDING ON identifier-6 ] 


mam 
22) 
fx 
Q 
Oo 
ee) 
S) 
Hi 
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Q 
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Oo 
o 
tH 
H 
n 
8 
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8 
Q 
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B 
sf 
3 
fe} 
Q 
0) 
— 


aa 


{ REPORT IS } report-name-1... ] 
naar } 


ees | 
< 
pd 
[ee 
fom 
fH 
fo) 
yy 
bh: 
5 
‘o 
bh 
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B 
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The BLOCK CONTAINS, DATA RECORD, LABEL RECORD, RECORDING MODE and VALUE OF 
clauses are syntactically recognized but are obsolete and non-functional. These clauses 
should not be coded in new programs. 
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The reserved words ARE, AT, CHARACTERS (RECORD clause only), CONTAINS, FROM, IN, 
IS, ON and WITH are optional and may be included, or not, at the discretion of the 
programmer. The presence or absence of these words has no effect upon the program. 


2. The terms RECORD IS and RECORDS ARE are interchangeable. 
3. The terms REPORT IS and REPORTS ARE are interchangeable. 
4. Only files intended for use as work files for either the SORT (see [SORT], page 391) or 


10. 


MERGE (see [MERGE], page 349) statements should be coded with an SD — all others 
should be defined with a FD. 


The sequence in which files are defined via FD or SD, as compared to the sequence in 
which their SELECT statements were coded, is irrelevant. 


The name specified as file-name-1 must exactly match the name specified on the file’s 
SELECT statement. 


The CODE-SET clause allows a custom alphabet, defined in the SPECIAL-NAMES (see 
[SPECIAL-NAMES], page 92) paragraph, to be associated with a file. This clause is 
valid only when used with sequential or line sequential files and usage can depend of the 
compiler version in use, platform used and other factors, see the NEWS file supplied 
with your version of the compiler for more details. 


The LINAGE clause may only be specified in the FD of a sequential or line sequential file. 
If used with a sequential file, the organization of that file will be implicitly changed 
to line sequential. The various components of the LINAGE clause define the layout of 
printed pages as follows: 


LINES AT TOP 
Number of unused (i.e. left blank) lines at the top of every page. The 
default if this if not specified is zero. 


LINES AT BOTTOM 
Number of unused (7.e. left blank) lines at the bottom of every page. The 
default if this if not specified is zero. 


LINAGE IS n LINES 
Total number of used/usable lines on the page. 


The sum of the previous three specifications should be the total number of possible 
lines available on one printed page. 


FOOTING AT 
Line number beyond which nothing may be printed except for any footing 
that is to appear on every page. The default for this if not specified is zero, 
meaning there will be no footings. This value cannot be larger than the 
LINAGE IS n LINES value. 


This page structure — once defined — can be automatically enforced by the WRITE 
statement (see [WRITE], page 417). 


Specifying a LINAGE clause in an FD will cause the LINAGE-COUNTER special register 
to be created for the file. This automatically-created data item will always contain the 
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current relative line number on the page being prepared which will serve as the starting 

point for a WRITE statement. 

The RECORD CONTAINS and RECORD IS VARYING clauses are ignored (with a warning 

message issued) when used with line sequential files. With other file organizations, 

these mutually-exclusive clauses define the length of data records within the file. The 
data item specified as identifier-6 must be defined within one of the record descriptions 
of file-name-1. 

The REPORT IS clause announces to the compiler that the file will be dedicated to the 

Report Writer Control System (RWCS); the clause names one or more reports, each to 

be described in the report section. The following special rules apply when the REPORT 

clause is used: 

A. The clause may only be specified in the FD of a sequential or line sequential file. If 
used with a sequential file, the organization of that file will be implicitly changed 
to line sequential. 

B. The FD cannot be followed by record descriptions. Detailed descriptions of data 
to be printed to the file will be defined in the REPORT SECTION (see [REPORT 
SECTION], page 135). 

C. Ifa LINAGE clause is also specified, Values specified for LINAGE IS and FOOTING AT 
will be ignored. The values of LINES AT BOTTOM and LINES AT TOP, if any, will be 
honoured. 


The following special rules apply only to sort/merge work files: 


A. Sort/merge work files should be assigned to DISK (or DISC) on their SELECT state- 
ments. 


B. Sorts and merges will be performed in memory, if the amount of data being sorted 
allows. 


C. Should actual disk work files be necessary due to the amount of data being sorted 
or merged, they will be automatically allocated to disk in a folder defined by: 


e The TMPDIR run-time environment variable (see [Run Time Environment 
Variables], page 654) 


e The TMP run-time environment variable 


e The TEMP run-time environment variable 


(in that order). 

D. These disk files will be automatically purged upon SORT or MERGE termination. 
They will also be purged if the program terminates abnormally before the SORT 
or MERGE finishes. Should you ever need to know, temporary sort /merge work files 
will be named cob*.tmp. 

E. If you specify a specific filename in the sort/merge work file’s SELECT, it will be 
ignored. 

See [Data Description Clauses], page 154, for information on the EXTERNAL and GLOBAL 

options. 
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6.2.2. FILE-SECTION-Data-Item 


FILE-SECTION-Data-Item Syntax j 


level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] 


rc 


BLANK WHEN ZERO ] 


JUSTIFIED RIGHT ] 


rm 


‘cam: | 


OCCURS [ integer-1 TO ] integer-2 TIMES 
ree cote as UNBOUNDED 


[ STEP identifier-6 ] 
[ ASCENDING|DESCENDING KEY IS identifier-3 ] 


[ PICTURE IS picture-string ] 

[ REDEFINES identifier-5 ] 

[ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ] 

[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] 

[ USAGE IS data-item-usage ] . [ FILE-SECTION-Data-Item ]... 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


Every sort file description (SD or FD) must be followed by at least one 01-level data item, 
except for file descriptions containing the REPORT IS clause. These 01-level data items, in 
turn, may be broken down into subordinate group and elementary items. An 01-level data 
item defined here in the file section is also known as a_ Record, even if it is an elementary 
item, provided that elementary item lacks the CONSTANT attribute. 


1. The reserved words BY, IS, KEY, ON and WHEN are optional and may be included, or not, 
at the discretion of the programmer. The presence or absence of these words has no 
effect upon the program. 


2. The reserved words SYNCRONIZED and SYNCRONIZED are interchangeable. Both may be 
abbreviated to SYNC. 
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The reserved word PICTURE may be abbreviated to PIC. 


As the syntax diagram shows, the definition of a FILE-SECTION-Data-Item is a recur- 
sive one in that there may be any number of such specifications coded following a FD 
or SD. The first such specification must have a level number of 01, and will describe 
a specific format of data record within the file. Specifications that follow that one 
may have level numbers greater than 01, in which case they are defining a hierarchical 
breakdown of the record. The definition of a record is terminated when one of the 
following occurs: 


Another 01-level item is found 
signifies the start of another record layout for the file. 


Another FD or SD is found 
marks the completion of the detailed description of the file and begins 
another. 


A division or section header is found 
also marks the completion of the detailed description of the file and signifies 
the end of the file section as well. 


5. Every FILE-SECTION-Data-Item description must be terminated with a period. 


6. If there are multiple record descriptions present for a given FD or SD, the one with the 


10. 
11. 


12. 


longest length will define the size of the record buffer into which a READ statement 
(see [READ], page 366) or a RETURN statement (see [RETURN], page 373) will deliver 
data read from the file and from which a WRITE statement (see [WRITE], page 417) or 
RELEASE statement (see [RELEASE], page 371) statement will obtain the data to be 
written to the file. 


The various 01-level record descriptions for a file description implicitly share that one 
common record buffer (thus, they provide different ways to view the structure of data 
that can exist within the file). Record buffers can be shared between files by using the 
SAME RECORD AREA (see [SAME RECORD AREA|, page 117) clause. 

The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 66, 77, 78 
and 88 all have special uses — See [Special Data Items], page 146, for details. 

Not specifying an identifier-1 or FILLER immediately after the level number has the 
same effect as if FILLER were specified. A data item named FILLER cannot be referenced 
directly; these items are generally used to specify an unused portion of the total storage 
allocated to a group item or to describe a group item whose contents which will only 
be referenced using the names of those items that belong to it. 

EXTERNAL cannot be combined with GLOBAL or REDEFINES. 


File section data buffers (and therefore all 01-level record layouts defined in the file 
section) are initialized to all binary zeros when the program is loaded into storage. 
See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 


Chapter 6 - DATA DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 129 


6.3. WORKING-STORAGE SECTION 


[ WORKING-STORAGE-SECTION-Data-Item Syntax 


level-number [ identifier-1 | FILLER ] [ IS GLOBAL | EXTERNAL ] 


[ BASED ] 
[ BLANK WHEN ZERO ] 
[ JUSTIFIED RIGHT ] 


rr 


OCCURS [ integer-1 TO ] integer-2 TIMES 
eae se a, UNBOUNDED 


fS3 


PICTURE IS picture-string ] 


[ REDEFINES identifier-5 ] 

[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] 
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] 

[ USAGE IS data-item-usage ] 


[ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]... 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


The working-storage section is used to describe data items that are not part of files, 
screens or reports and whose data values persist throughout the execution of the program. 


1. The reserved words BY, CHARACTER, IS, KEY, ON, RIGHT (JUSTIFIED), TIMES and WHEN 
are optional and may be included, or not, at the discretion of the programmer. The 
presence or absence of these words has no effect upon the program. 


2. The reserved words SYNCRONIZED and SYNCHRONISED are interchangeable. Both may 
be abbreviated as SYNC. 
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The reserved word PICTURE may be abbreviated to PIC. 


4. The reserved word JUSTIFIED may be abbreviated to JUST. 


10. 


11. 


As the syntax diagram shows, the definition of a WORKING-STORAGE-SECTION-Data- 
Item is a recursive one in that there may be any number of such specifications coded 
following one another. The first such specification must have a level number of 01. 
Specifications that follow that one may have level numbers greater than 01, in which 
case they are defining a hierarchical breakdown of a record. The definition of a record 
is terminated when one of the following occurs: 


e Another 01-level item is found — this signifies the end of the definition of one 
record and the start of a another. 


e A 77-level item is found — this signifies the end of the definition of the record and 
begins the definition of a special data item; See [77-Level Data Items], page 151, 
for more information. 


e A division or section header is found — this also marks the completion of a record 
and signifies the end of the working-storage section as well. 


Every WORKING-STORAGE-SECTION-Data-Item description must be terminated with a 
period. 


The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 
49 are used to define data items that may be part of a hierarchical structure. Level 
number 01 can also be used to define a constant — an item with an unchangeable value 
specified at compilation time. 


Level numbers 66, 77, 78 and 88 all have special uses — See [Special Data Items], 
page 146, for details. 


Not specifying an identifier-1 or FILLER immediately after the level number has the 
same effect as if FILLER were specified. A data item named FILLER cannot be referenced 
directly; these items are generally used to specify an unused portion of the total storage 
allocated to a group item or to describe a group item whose contents which will only 
be referenced using the names of those items that belong to it. 


Data items defined within the working-storage section are automatically initialized once 
— as the program in which the data is defined is loaded into memory. Subprograms 
may be loaded into memory more than once (see the CANCEL statement (see [CANCEL], 
page 298)), in which case initialization will happen each time they are loaded. See [Data 
Initialization], page 26, for a discussion of the initialization rules. 


See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.4. LOCAL-STORAGE SECTION 


[ LOCAL-STORAGE-SECTION-Data-Item Syntax 


level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] 


[ BASED ] 


on] 
ies] 
Ee 
Pd 
= 
w 
= 
an 
fH 
a 
N 
cz 
w 
(o) 
wi 


JUSTIFIED RIGHT ] 


re 


mo 


OCCURS [ integer-1 TO ] integer-2 TIMES 
attri . UNBOUNDED 


[ PICTURE IS picture-string ] 

[ REDEFINES identifier-5 ] 

[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] 
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] 

[ USAGE IS data-item-usage ] 


[ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]... 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


The local-storage section is similar to working-storage, but describes data within a sub- 
program that will be dynamically allocated and initialized (automatically) each time the 
subprogram is executed. See [Data Initialization], page 26, for the rules of data initializa- 
tion. 


1. The reserved words BY, CHARACTER IS, KEY, ON, RIGHT (JUSTIFIED), TIMES and WHEN 
are optional and may be included, or not, at the discretion of the programmer. The 
presence or absence of these words has no effect upon the program. 
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The reserved words SYNCRONIZED and SYNCHRONISED are interchangeable. Both may 
be abbreviated as SYNC. 


The reserved word PICTURE may be abbreviated to PIC. 


4. The reserved word JUSTIFIED may be abbreviated to JUST. 


10. 
11. 


As the syntax diagram shows, the definition of a LOCAL-STORAGE-SECTION-Data-Item 
is a recursive one in that there may be any number of such specifications coded following 
one another. The first such specification must have a level number of 01. Specifications 
that follow that one may have level numbers greater than 01, in which case they are 
defining a hierarchical breakdown of a record. The definition of a record is terminated 
when one of the following occurs: 


e Another 01-level item is found — this signifies the end of the definition of one 
record and the start of a another. 


e A division or section header is found — this also marks the completion of a record 
and signifies the end of the local-storage section as well. 


Every LOCAL-STORAGE-SECTION-Data-Item description must be terminated with a pe- 
riod. 

The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 
49 are used to define data items that may be part of a hierarchical structure. Level 
number 01 can also be used to define a constant — an item with an unchangeable value 
specified at compilation time. 


Level numbers 66, 77, 78 and 88 all have special uses — See [Special Data Items], 
page 146, for details. 

Not specifying an identifier-1 or FILLER immediately after the level number has the 
same effect as if FILLER were specified. A data item named FILLER cannot be referenced 
directly; these items are generally used to specify an unused portion of the total storage 
allocated to a group item or to describe a group item whose contents which will only 
be referenced using the names of those items that belong to it. 


Local-storage cannot be used in nested subprograms. 


See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.5. LINKAGE SECTION 


f LINKAGE-SECTION-Data-Item Syntax 


level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ] 


[ ANY LENGTH ] 
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[ PICTURE IS picture-string ] 

[ REDEFINES identifier-6 ] 

[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] 

[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ] 

[ USAGE IS data-item-usage ] . [ LINKAGE-SECTION-Data-Item ]... 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


The linkage section describes data within a subprogram that serves as either input ar- 
guments to or output results from the subprogram. 


1. The reserved words BY, CHARACTER, IS, KEY, ON and WHEN are optional and may be 
included, or not, at the discretion of the programmer. The presence or absence of these 
words has no effect upon the program. 


2. The reserved words SYNCRONIZED and “SYNCHRONISED” are interchangeable. Both may 
be abbreviated as SYNC. 


3. The reserved word PICTURE may be abbreviated to PIC. 
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4. The reserved word JUSTIFIED may be abbreviated to JUST. 


10. 


11. 


12. 


As the syntax diagram shows, the definition of a LINKAGE-SECTION-Data-Item is a 
recursive one in that there may be any number of such specifications coded following 
one another. The first such specification must have a level number of 01. Specifications 
that follow that one may have level numbers greater than 01, in which case they are 
defining a hierarchical breakdown of a record. The definition of a record is terminated 
when one of the following occurs: 


e Another 01-level item is found — this signifies the end of the definition of one 
record and the start of a another. 


e A division or section header is found — this also marks the completion of a record 
and signifies the end of the linkage section as well. 


Every LINKAGE-SECTION-Data-Item description must be terminated with a period. 


The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 
49 are used to define data items that may be part of a hierarchical structure. Level 
number 01 can also be used to define a constant — an item with an unchangeable value 
specified at compilation time. 


Level numbers 66, 77, 78 and 88 all have special uses — See [Special Data Items], 
page 146, for details. 


It is expected that: 


A. A linkage section should occur only within a subprogram. The compiler will not 
prevent its use in a main program, however. 


B. All 01-level data items described within a subprogram’s linkage section should 
appear in a PROCEDURE DIVISION USING (see [PROCEDURE DIVISION USING], 
page 248) or as arguments on an ENTRY statement. 


C. Each 01-level data item described within a subprogram’s linkage section should 
correspond to an argument passed on a CALL statement (see [CALL], page 293) or 
an argument on a function call to the subprogram. 


Not specifying an identifier-1 or FILLER immediately after the level number has the 
same effect as if FILLER were specified. A data item named FILLER cannot be referenced 
directly; these items are generally used to specify an unused portion of the total storage 
allocated to a group item or to describe a group item whose contents which will only 
be referenced using the names of those items that belong to it. In the linkage section, 
01-level data items cannot be named FILLER. 


No storage is allocated for data defined in the linkage section; the data descriptions 
there are merely defining storage areas that will be passed to the subprogram by a 
calling program. Therefore, any discussion of the default initialization of such data 
is irrelevant. It is possible, however, to manually allocate linkage section data items 
that aren’t subprogram arguments via the ALLOCATE statement (see [ALLOCATE], 
page 290) statement. In such cases, initialization will take place as per the documen- 
tation of that statement. 


See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.6. REPORT SECTION 


[ REPORT SECTION Syntax 


[ REPORT SECTION. 


{ Report-Description [ { Report-Group-Definition } ]... }... ] 
{ { 01-Level-Constant } } 
{ { 78-Level-Constant } } 
{ 01-Level-Constant } 
{ 78-Level-Constant } 


f Report-Description (RD) Syntax 


[ CODE IS literal-1 | identifier-1 ] 
[ { CONTROL IS } | oe 
dee Sng wee Peet oe OR } 

} } 


{ identifier-2 


] 


[ PAGE [ { LIMIT IS }] [ { literal-2 } LINES ] 
EAS Le ER } { identifier-3 } ~~~~ 


rm 


literal-3 | identifier-4 COLUMNS|COLS ] 


| rai 


HEADING IS literal-4 | identifier-5 ] 


r1. 


FIRST DE|DETAIL IS literal-5 | identifier-6 ] 


| ame f 


LAST CH|{CONTROL HEADING} IS literal-6 | identifier-7 ] 


LAST DE|DETAIL IS literal-7 | identifier-8 ] 


oa? 


| coe | 


FOOTING IS literal-8 | identifier-9 ] ] 


This section describes the layout of printed reports as well as many of the functional aspects 
of the generation of reports that will be produced via the Report Writer Control System. 
It is important to maintain the order of these clauses and ensure that all fields defined or 
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referenced with this section are actually defined in the WORKING-STORAGE SECTION and not 
elsewhere. 


1. The reserved words ARE and IS are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 
2. The phrases CONTROL IS and CONTROLS ARE are interchangeable, as are the PAGE LIMIT 
and PAGE LIMITS phrases. 
3. The reserved word LINES may be abbreviated as LINE. 
4. The reserved word COLUMNS may be abbreviated as COLS. 
5. Each report referenced on a REPORT IS clause (see [File/Sort-Description], page 124) 
must be described with a report description (RD). 
6. See [GLOBAL], page 176, for information on the GLOBAL option. 
7. Please see [Report Writer Features], page 25, if you have not read it already. It will 
familiarize you with the Report Writer terminology that follows. 
8. The following rules pertain to the PAGE LIMITS clause: 
A. If no PAGE LIMITS clause is specified, the entire report will be generated as if it 
consists of a single arbitrarily long page. 
B. All literals (literal-2 through literal-8) must be numeric with non-zero positive 
integer values. 
C. All identifiers (identifier-2 through identifier-8) must be numeric, unedited with 
non-zero positive integer values. 


D. Any value specified for literal-2 or identifier-2 will define the total number of 
available lines on any report page, not counting any unused margins at the top 
and/or bottom of the page (defined by the LINES AT TOP and LINES AT BOTTOM 
values specified on the LINAGE clause of the FD this RD is linked to — see [File/Sort- 
Description], page 124). 

E. Any value specified for literal-3 or identifier-3 will be ignored. 

F. The HEADING clause defines the first line number at which a report heading or 
page heading may be presented. 

G. The FIRST DETAIL clause defines the first line at which a detail group may be 
presented. 

H. The LAST CONTROL HEADING clause defines the last line at which any line of a 
control heading may be presented. 

I. The LAST DETAIL clause defines the last line at which any line of a detail group 
may be presented. 

J. The FOOTING clause defines the last line at which any line of a control footing 
group may be presented. 


K. The following rules establish default values for the various PAGE LIMIT clauses, 
assuming there is one: 


HEADING default is one (1) 


FIRST DETAIL HEADING 
value is used 
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LAST CONTROL HEADING 
value from LAST DETAIL or, if that is absent, the value from FOOTING 
or, if that too is absent, the value from PAGE LIMIT 


LAST DETAIL 
value from FOOTING or, if that is absent, the value from PAGE LIMIT 


FOOTING value from LAST DETAIL or, if that is absent, the value from PAGE 
LIMIT 


For the values specified on a PAGE LIMIT clause to be valid, all of the following 
must be true: 


e FIRST DETAIL < HEADING 

e LAST CONTROL HEADING < FIRST DETAIL 
e LAST DETAIL < LAST CONTROL HEADING 
e FOOTING < LAST DETAIL 


9. The following rules pertain to the CONTROL clause: 


A. 


If there is no CONTROL clause, the report will contain no control breaks; this implies 
that there can be no CONTROL HEADING or CONTROL FOOTING report groups defined 
for this RD. 


. Include the reserved word FINAL if you want to include a special control heading 


before the first detail line is generated (CONTROL HEADING FINAL) or after the last 
detail line is generated (CONTROL FOOTING FINAL). 


If you specify FINAL, it must be the first control break named in the RD. 


Any identifier-9 specifications included on the CONTROL clause are referencing data 
names defined in any data division section except for the report section. 


There must be a CONTROL HEADING and/or CONTROL FOOTING report group defined 
in the report section for each identifier-9. 


At execution time: 


e Each time a GENERATE statement (see [GENERATE], page 332) is executed 
against a detail report group defined for this RD, the RWCS will check the 
contents of each identifier-2 data item; whenever an identifier-9’s value has 
changed since the previous GENERATE, a control break condition will be in 
effect for that identifier-2. 


e Once the list of control breaks has been determined, the CONTROL FOOTING for 
each identifier-2 having a control break (if any such report group is defined) 
will be presented. 


e Next, the CONTROL HEADING for each identifier-2 having a control break (if any 
such report group is defined) will be presented. 

e The CONTROL FOOTING and CONTROL HEADING report groups will be presented 
in the sequence in which they are listed on the CONTROL clause. 


e Only after this processing has occurred will the detail report group specified 
on the GENERATE be presented. 
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10. Each RD will have the following allocated for it: 
A. The PAGE-COUNTER special register (see [Special Registers], page 265), which will 
contain the current report page number. 


e This register will be set to a value of 1 when an INITIATE statement (see 
[INITIATE], page 343) is executed for the report and will be incremented by 
1 each time the RWCS starts a new page of the report. 


e References to PAGE-COUNTER within the report section will be implicitly qual- 
ified with the name of the report to which the report group referencing the 
register belongs. 

e References to PAGE-COUNTER in the procedure division must be qualified with 
the appropriate report name if there are multiple RDs defined. 

B. The LINE-COUNTER special register, which will contain the current line number 
on the current page. 
11. The RD must be followed by at least one 01-level report group definition. 
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6.6.1. Report Group Definitions 


Report-Group-Definition Syntax 


01 [ identifier-1 ] 


[ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ] 


eng? He ee te eee gS } 
{ +|PLUS integer-1 } 
te eye ee, i 
{ ON NEXT PAGE } 


[ NEXT GROUP IS { [ +|PLUS ] integer-2 } ] 
COU tg { Cpa } 
{ NEXT|{NEXT PAGE}|PAGE } 


[ TYPE IS { RH|{REPORT HEADING} | 
aera ee Ay eh ne ee } 
{ PH|{PAGE HEADING} } 
fate TP eae } 
{ CH| {CONTROL HEADING} FINAL|identifier-2 } 
fe Ow SNES CRG | Te Aetrae ts } 
{ DE|DETAIL } 
a } 
{ CF|{CONTROL FOOTING} FINAL|identifier-2 } 
He TENN Seiadge ogee » SuPNae } 
{ PF|{PAGE FOOTING} F 
ae Tevceo pS, er } 
{ RF|{REPORT FOOTING} F 


[ REPORT-SECTION-Data-Item ]... 


The syntax shown here documents how a report group is defined to a report. This syntax 
is valid only in the report section, and only then after an RD. 


1. The reserved words IS, NUMBER and ON are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


2. The RH and REPORT HEADING terms are interchangeable, as are PH and PAGE HEADING, CH 
and CONTROL HEADING, DE and DETAIL, CF and CONTROL FOOTING, PF and PAGE FOOTING 
as well as RF and REPORT FOOTING. 


3. The report group being defined will be a part of the most-recently coded RD. 
4. The TYPE (see [TYPE], page 222) clause specifies the type of report group being defined. 


5. The level number used for a report group definition must be 01. 
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6. The optional identifier-1 specification assigns a name to this report group so that 
the group may be referenced either by a GENERATE statement or on a USE BEFORE 
REPORTING. 

7. No two report groups in the same report (RD) may named with the same identifier-1. 
There may, however, be multiple identifier-1 definitions in different reports. In such 
instances, references to identifier-1 must be qualified by the report name. 

8. There may only be one report heading, report footing, final control heading, final 
control footing, page heading and page footing defined per report. 

9. Report group declarations must be followed by at least one REPORT-SECTION-Data- 
Item with a level number in the range 02-49. 

10. See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.6.2. REPORT SECTION Data Items 


REPORT-SECTION-Data-Item Syntax 


level-number [ identifier-1i ] 


mam 


BLANK WHEN ZERO ] 
COLUMN [ { NUMBER IS }] [ +|PLUS ] integer-1 ] 
nnn { n~nwnwnwwe } nnwwe 
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JUSTIFIED RIGHT ] 
LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] 
eens { +|PLUS integer-2 ~~~~ ~~"~ 
{ n~nwnwne 
{ ON NEXT PAGE 
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[ STEP integer-5 ] 


{ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ] 
Faas ~~~ { integer-6 } ~~ { integer-7 } 


[ PICTURE IS picture-string ] 

[ PRESENT WHEN condition-name ] 

[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ] 

[ { SOURCE IS literal-1|identifier-6 [ ROUNDED ] +] 
Tg } 
{ SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] } 
{~~~ { literal-2  } Ri 8 ee. a 
{ VALUE IS [ ALL ] literal-3 { UPON identifier-9 +} } 


[ REPORT-SECTION-Data-Item ]... 
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Data item descriptions describing the report lines and fields that make up the substance of 
a report group immediately follow the definition of that group. 


1. The reserved words IS, NUMBER, OF, ON, RIGHT, TIMES and WHEN (BLANK) are optional 
and may be omitted. The presence or absence of these words has no effect upon the 
program. 

The reserved word COLUMN may be abbreviated as COL. 

The reserved word JUSTIFIED may be abbreviated as JUST. 

The reserved word PICTURE may be abbreviated as PIC. 

The SOURCE (see [SOURCE], page 215), SUM (see [SUM], page 516) and VALUE (see 
[VALUE], page 244) clauses, valid only on an elementary item, are mutually-exclusive 
of each other. 


Chee be 


6. Group items (those without PICTURE clauses) are frequently used to describe entire 
lines of a report, while elementary items (those with a picture clause) are frequently 
used to describe specific fields of information on the report. When this coding conven- 
tion is being used, group items will have LINE (see [LINE], page 183) clauses and no 
COLUMN (see [COLUMN], page 166) clauses while elementary items will be specified the 
other way around. 


7. See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.7. SCREEN SECTION 


[ SCREEN-SECTION-Data-Item Syntax 


level-number [ identifier-1 | FILLER ] 
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COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ] 


[ CONSTANT | EMPTY CHECK ] 
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FROM literal-1 | identifier-5 } ] 
piety } 
TO identifier-5 


BAA AAA 


} 
} 
USING identifier-5 } 
} 
} 


{ VALUE IS [ ALL ] literal-1 


FULL | LENGTH-CHECK ] [ REQUIRED | EMPTY-CHECK ] [ SECURE | NO-ECHO ] 
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LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ] 


LOWER | UPPER ] 
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PICTURE IS picture-string ] 


PROMPT [ CHARACTER IS literal-2 | identifier-7 ] 


SCROLL DOWN | SCROLL UP | SIZE | TIME OUT ] 


UPDATE ] 


{ SCREEN-SECTION-Data-Item ]... 


The screen section describes the screens to be displayed during terminal/console I-O. 


1. 


The reserved words CHARACTER (SEPARATE clause), IS, NUMBER, RIGHT, TIMES and WHEN 
are optional and may be omitted. The presence or absence of these words has no effect 
upon the program. 


2. The reserved word COLUMN may be abbreviated as COL. 
3. The reserved word PICTURE may be abbreviated as PIC. 


4. The following sets of reserved words are interchangeable: 


e AUTO, AUTO-SKIP and AUTOTERMINATE 

e BACKGROUND-COLOR and BACKGROUND-COLOUR 
e BELL and BEEP 

e FOREGROUND-COLOR and FOREGROUND-COLOUR 
e FULL and LENGTH-CHECK 

e REQUIRED and EMPTY-CHECK 

e SECURE and NO-ECHO 


Data items defined in the screen section describe input, output or combination screen 
layouts to be used with ACCEPT data-item statement (see [ACCEPT data-item], 
page 272) or DISPLAY data-item statement (see [DISPLAY data-item], page 311) 
statements. These screen layouts may define the entire available screen area or any 
subset of it. 


The term available screen area is a nebulous one in those environments where command- 
line shell sessions are invoked within a graphical user-interface environment, as will be 
the case on Windows, OSX and most Unix/Linux systems — these environments allow 
command-line session windows to exist with a variable number of available screen rows 
and columns. When you are designing GnuCOBOL screens, you need to do so with 
an awareness of the logical screen row/column geometry the program will be executing 
within. 

Data items with level numbers 01 (Constants), 66, 78 and 88 may be used in the screen 
section; they have the same syntax, rules and usage as they do in the other data division 
sections. 
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8. 


10. 


11. 


Without LINE (see [LINE], page 183) or COLUMN (see [COLUMN], page 166) clauses, 
screen section fields will display on the console window beginning at whatever 
line/column coordinate is stated or implied by the ACCEPT data-item or DISPLAY 
data-item statement that presents the screen item. After a field is presented to the 
console window, the next field will be presented immediately following that field. 


A LINE clause explicitly stated in the definition of a screen section data item will 
override any LINE clause included on the ACCEPT data-item or DISPLAY data-item 
statement that presents that data item to the screen. The same is true of COLUMN 
clauses. 


The Tab and Back-Tab (Shift-Tab on most keyboards) keys will position the cursor 
from field to field in the line/column sequence in which the fields occur on the screen 
at execution time, regardless of the sequence in which they were defined in the screen 
section. 


See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.8. Special Data Items 


6.8.1. 01-Level Constants 


[ 01-Level-Constant Syntax 


01 constant-name-1 CONSTANT [ IS GLOBAL ] 


{ AS { arithmetic-espression-1 #}. 
{ { literal-1 Po 
{ { { BYTE-LENGTH } OF { identifier-1 } } } 
{ te SESE ee } { usage-name } } } 
{ { { LENGTH } ys 
es. 5 “Se Gi } 
{ FROM CDF-variable-name-1 } 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, SCREEN. 


The Ol-level constant is one of five types of compilation-time constants that can 
be declared within a program. The other four types are >>DEFINE CDF directive (see 
[>>DEFINE], page 68) constants, >>SET CDF directive (see [>>SET], page 71) constants, 
78-level constants (see [78-Level Data Items], page 152, and arithmetic-espression-1). 


1. The reserved words AS, IS and OF are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. See [GLOBAL], page 176, for information on the GLOBAL option. 

3. This particular type of constant declaration provides the ability to determine the length 
of a data item or the storage size associated with a particular numeric USAGE (see 
[USAGE], page 232) type — something not possible with the other types of constants. 


4. Constants defined in this way become undefined once an END PROGRAM or END FUNCTION 
is encountered in the input source. 


5. Data descriptions of this form do not actually allocate any storage — they merely 
define a name (constant-name-1) that may be used anywhere a numeric literal (see 
BYTE-LENGTH or LENGTH options) or a literal of the same type as literal-1 may be used. 

6. The constant-name-1 name may not be referenced on a CDF directive. 

7. Care must be taken that constant-name-1 does not duplicate any other data item name 
that has been defined in the program as references to that data item name will refer to 
the constant and not the data item. The GnuCOBOL compiler will not issue a warning 
about this condition. 

8. The value specified for usage-name may be any USAGE that does not use a PICTURE (see 
[PICTURE], page 194) clause. These would be any of BINARY-C-LONG, BINARY-CHAR, 
BINARY-DOUBLE, BINARY-LONG, BINARY-SHORT, COMP-1 (or COMPUTATIONAL-1), 
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COMP-2 (or COMPUTATIONAL-2), FLOAT-DECIMAL-16, FLOAT-DECIMAL-34, FLOAT-LONG, 
FLOAT-SHORT, POINTER, or PROGRAM-POINTER. 
9. The BYTE-LENGTH clause will produce a numeric value for constant-name-1 identical to 
that which would be returned by the BYTE-LENGTH intrinsic function executed against 
identifier-1 or a data item declared with a USAGE of usage-name. 


10. 


The LENGTH clause will produce a numeric value for constant-name-1 identical to that 


which would be returned by the LENGTH intrinsic function executed against identifier-1 
or a data item declared with a USAGE of usage-name. 


Here is an example of using the option arithmetic-espression. 


PROGRAM-ID. TESTCONST. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 A CONSTANT 2. 

01 B CONSTANT ( (3 + 2) * A). 

01 CON CONSTANT (A ** B). 

01 MYDATA PIC X(CON). 

PROCEDURE DIVISION. 

DISPLAY CON 

ACCEPT omitted 

MOVE 
DISPLAY MYDATA 
ACCEPT omitted 
GOBACK. 


"123456789012345678901234567890" 


TO MYDATA 


Here is the listing of a GnuCOBOL program that uses 01-level constants to display the 
length (in bytes) of the various picture-less usage types. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. Usage-Lengths. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 Len-BINARY-C-LONG CONSTAN 
01 Len-BINARY-CHAR CONSTAN 
01 Len-BINARY-DOUBLE CONSTAN 
01 Len-BINARY-LONG CONSTAN 
01 Len-BINARY-SHORT CONSTAN 
01 Len-COMP-1 CONSTAN 
01 Len-COMP-2 CONSTAN 
01 Len-FLOAT-DECIMAL-16 CONSTAN 
01 Len-FLOAT-DECIMAL-34 CONSTAN 
01 Len-FLOAT-LONG CONSTAN 
01 Len-FLOAT-SHORT CONSTAN 
01 Len-POINTER CONSTAN 
01 Len-PROGRAM-POINTER CONSTAN 


PROCEDURE DIVISION. 


15 January 2023 


T 
T 
T 
T 
T 
T 
T 
T 
T 
T 
T 
T 
T 


AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 
AS 


LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 
LENGTH 


OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 


BINARY-C-LONG. 
BINARY-CHAR. 
BINARY-DOUBLE. 
BINARY-LONG. 
BINARY-SHORT . 
COMP-1. 
COMP-2. 


FLOAT-DECIMAL-16. 
FLOAT-DECIMAL-34. 


FLOAT-LONG. 
FLOAT-SHORT . 
POINTER. 
PROGRAM-POINTER. 
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000-Main. 
DISPLAY "On this system, with this build of GnuCOBOL, the" 
DISPLAY "PICTURE-less USAGE’s have these lengths (in bytes):" 


DISPLAY " " 

DISPLAY "BINARY-C-LONG: " Len-BINARY-C-LONG 
DISPLAY "BINARY-CHAR: " Len-BINARY-CHAR 
DISPLAY "BINARY-DOUBLE: " Len-BINARY-DOUBLE 
DISPLAY "BINARY-LONG: " Len-BINARY-LONG 
DISPLAY "BINARY-SHORT: " Len-BINARY-SHORT 
DISPLAY "COMP-1: " Len-COMP-1 
DISPLAY "COMP-2: " Len-COMP-2 


DISPLAY "FLOAT-DECIMAL-16: " Len-FLOAT-DECIMAL-16 
DISPLAY "FLOAT-DECIMAL-34: " Len-FLOAT-DECIMAL-34 


DISPLAY "FLOAT-LONG: " Len-FLOAT-LONG 
DISPLAY "FLOAT-SHORT: " Len-FLOAT-SHORT 
DISPLAY "POINTER: " Len-POINTER 

DISPLAY "PROGRAM-POINTER: " Len-PROGRAM-POINTER 
STOP RUN. 


The output of this program, on a Windows 7 system with a 32-bit MinGW build of 
GnuCOBOL is: 


On this system, with this build of GnuCOBOL, the 
PICTURE-less USAGE’s have these lengths (in bytes): 


BINARY-C-LONG: 4 
BINARY-CHAR: 1 
BINARY-DOUBLE: 8 
BINARY-LONG: 4 
BINARY-SHORT: 2 
COMP-1: 4 
COMP-2: 8 
FLOAT-DECIMAL-16: 8 
FLOAT-DECIMAL-34: 16 
FLOAT-LONG: 8 
FLOAT-SHORT: 4 
POINTER: 4 
PROGRAM-POINTER: 4 


The output of this program, on a Linux X64 system running cobc (GnuCOBOL) 3.1.2.0 is: 


On this system, with this build of GnuCOBOL, the 
PICTURE-less USAGE’s have these lengths (in bytes): 


BINARY-C-LONG: 8 
BINARY-CHAR: 1 
BINARY-DOUBLE: 8 
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BINARY-LONG: 4 
BINARY-SHORT : 2 
COMP-1: 4 
COMP-2: 8 
FLOAT-DECIMAL-16: 8 
FLOAT-DECIMAL-34: 16 
FLOAT-LONG: 8 
FLOAT-SHORT : 4 
POINTER: 8 
PROGRAM-POINTER: 8 


Spot the differences between 32 and 64 bit. 
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6.8.2. 66-Level Data Items 


( 66-Level-Data-Item Syntax } 


66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE 


A 66-level data item regroups previously defined items by specifying alternative, possibly 
overlapping, groupings of elementary data items. 


1. The reserved words THRU and THROUGH are interchangeable. 
2. A level-66 data item cannot rename a level-66, level-01, level-77, or level-88 data item. 


3. There may be multiple level-66 data items that rename data items contained within 
the same 01-level record description. 


4. All RENAMES entries associated with one logical record must immediately follow that 
record’s last data description entry. 
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6.8.3. 77-Level Data Items 


( 77-Level-Data-Item Syntax 


77 identifier-1 [ IS GLOBAL|EXTERNAL ] 


[ BASED ] 
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USAGE IS data-item-usage ] 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


This syntax is valid in the following sections: WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE 

The intent of a 77-level item is to be able to create a stand-alone elementary data item. 

1. The reserved words CHARACTER, IS, RIGHT (JUSTIFIED) and WHEN are optional and 

may be omitted. The presence or absence of these words has no effect upon the program. 


2. The reserved word JUSTIFIED may be abbreviated as JUST, the reserved word PICTURE 
may be abbreviated as PIC and the reserved words SYNCRONIZED and SYNCHRONISED 
may be abbreviated as SYNC. 


3. New programs requiring a stand-alone elementary item should be coded to use a level 
number of 01 rather than 77. 


4. See [Data Description Clauses], page 154, for information on the usage of the various 
data description clauses. 
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6.8.4. 78-Level Data Items 


( 78-Level-Constant Syntax } 


78 constant-name-1 VALUE IS literal-1. 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, SCREEN 

The 78-level constant is one of four types of compilation-time constants that can be 
declared within a program. The other three types are >>DEFINE CDF directive (see 
[>>DEFINE], page 68) constants, >>SET CDF directive (see [>>SET], page 71) constants 
and 01-level constants (see [01-Level Constants], page 146). 

1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 

2. Constants defined in this way become undefined once an END PROGRAM or END FUNCTION 
is encountered in the input source. 

3. Data descriptions of this form do not actually allocate any storage — they merely 
define a name (constant-name-1) that may be used anywhere a literal of the same type 
as literal-1 may be used. 

4. The constant-name-1 name may not be referenced on a CDF directive. 

5. Care must be taken that constant-name-1 does not duplicate any other data item name 
that has been defined in the program as references to that data item name will refer to 
the constant and not the data item. The GnuCOBOL compiler will not issue a warning 
about this condition. 
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6.8.5. 88-Level Data Items 


( 88-Level-Data-Item Syntax 


88 condition-name-1 { VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}... 
oe er Be es 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 


Condition names are Boolean (i.e. TRUE / FALSE) data items that receive their TRUE 
and FALSE values based upon the values of the non 88-level data item whose definition they 
immediately follow. 


1. The reserved words ARE, IS, SET and TO are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 

2. The reserved words THRU and THROUGH are interchangeable. 

3. Condition names are always defined subordinate to another (non 88-level) data item. 
That data item must be an elementary item. Whenever the parent data item assumes 
one of the values specified on the 88-level item’s VALUE (see [VALUE], page 244) clause, 
condition-name-1 will take on the value of TRUE. 

4. Condition names do not occupy any storage. 

5. The optional THROUGH clause allows a range of possible TRUE values to be specified. 

6. Whenever the parent data item assumes any value except one of the values specified on 
condition-name-1’s VALUE clause, condition-name-1 will take on the value of FALSE. 


7. Executing the statement SET condition-name-1 TO TRUE will cause condition-name- 
1’s parent data item to take on the first value specified on condition-name-1’s VALUE 
clause. 

8. Executing the statement SET condition-name-1 TO FALSE will cause condition-name- 
1’s parent data item to take on the value specified on condition-name-1’s FALSE clause. 
If condition-name-1 does not have a FALSE clause, the SET (see [SET], page 382) state- 
ment will generate an error message at compilation time. 


9. See [Condition Names], page 45, for more information. 
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6.9. Data Description Clauses 


6.9.1. ANY LENGTH 


( ANY LENGTH Attribute Syntax ] 


ANY LENGTH 


This syntax is valid in the following sections: LINKAGE 


Data items declared with the ANY LENGTH attribute have no fixed compile-time length. 
Such items may only be defined in the linkage section of a subprogram as they may only serve 
as subroutine argument descriptions. These items must have a PICTURE (see [PICTURE], 
page 194) clause that specifies exactly one A, X or 9 symbol. 

1. The ANY LENGTH and BASED (see [BASED], page 160) clauses cannot be used together 
in the same data item description. 
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6.9.2. AUTO 


( AUTO Attribute Syntax } 


This syntax is valid in the following sections: SCREEN 


A field whose description includes this attribute will cause the cursor to automatically 
advance to the next input-enabled field of a screen if the field is completely filled with input 
data. 

1. The AUTO, AUTO-SKIP (see [AUTO-SKIP], page 156) and AUTOTERMINATE (see 
[AUTOTERMINATE], page 157) clauses are interchangeable, and may not be used 
together in the same data item description. 
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6.9.3. AUTO-SKIP 


( AUTO-SKIP Attribute Syntax } 


AUTO-SKIP 


This syntax is valid in the following sections: SCREEN 


A field whose description includes this attribute will cause the cursor to automatically 
advance to the next input-enabled field of a screen if the field is completely filled with input 
data. 

1. The AUTO (see [AUTO], page 155), AUTO-SKIP and AUTOTERMINATE (see 
[AUTOTERMINATE], page 157) clauses are interchangeable, and may not be used 
together in the same data item description. 
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6.9.4. AUTOTERMINATE 


( AUTOTERMINATE Attribute Syntax } 


AUTOTERMINATE 


This syntax is valid in the following sections: SCREEN 


A field whose description includes this attribute will cause the cursor to automatically 
advance to the next input-enabled field of a screen if the field is completely filled with input 
data. 

1. The AUTO (see [AUTO], page 155), AUTO-SKIP (see [AUTO-SKIP], page 156) and 
AUTOTERMINATE clauses are interchangeable, and may not be used together in the same 
data item description. 
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6.9.5. BACKGROUND-COLOR 


( BACKGROUND-COLOR Attribute Syntax } 


BACKGROUND-COLOR| BACKGROUND-COLOUR IS integer-1 | identifier-1 


This syntax is valid in the following sections: SCREEN 
This clause is used to specify the screen background color of the screen data item or the 
default screen background color of subordinate items if used on a group item. 
1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 
2. The reserved words BACKGROUND-COLOR and BACKGROUND-COLOUR are interchangeable. 
3. You specify colors by number (0-7), or by using the constant names provided in the 
screenio.cpy copybook (provided with all GnuCOBOL source distributions). 
4. Colors may also be specified using a numeric non-edited identifier whose value is in the 
range 0-7. 
For composite DISPLAY’s, the attributes are always only applied to the previous source- 
item but the following also allows a change by variable or literal 7.e. 


DISPLAY "Name: " BACKGROUND-COLOR COB-YELLOW 
NAME-VAR BACKGROUND-COLOR COB-BLACK 
END-DISPLAY 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.5B. BEFORE TIME 


( BEFORE TIME Attribute Syntax ] 


BEFORE TIME 


This syntax is valid in the following sections: SCREEN 
This clause is used to specify time sequence etc, etc, etc. NEEDS CONTENT HERE. 
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6.9.6. BASED 


( BASED Attribute Syntax } 


This syntax is valid in the following sections: WORKING-STORAGE, LOCAL-STORAGE, LINKAGE 


Data items declared with BASED are allocated no storage at compilation time. At run- 
time, the ALLOCATE (see [ALLOCATE], page 290) or SET ADDRESS (see [SET ADDRESS], 
page 384) statements are used to allocate space for and (optionally) initialize such items. 


1. The BASED and ANY LENGTH (see [ANY LENGTH], page 154) clauses cannot be used 
together in the same data item description. 


2. The BASED clause may only be used on level 01 and level 77 data items. 
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6.9.7. BEEP 


( BEEP Attribute Syntax } 


This syntax is valid in the following sections: SCREEN 


1. The BEEP and BELL (see [BELL], page 162) clauses are interchangeable, and may not 
be used together in the same data item description. 


2. Use this clause to cause an audible tone to occur when the screen item is DISPLAYed. 
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6.9.8. BELL 


( BELL Attribute Syntax } 


This syntax is valid in the following sections: SCREEN 


1. The BEEP (see [BEEP], page 161) and BELL clauses are interchangeable, and may not 
be used together in the same data item description. 


2. Use this clause to cause an audible tone to occur when the screen item is DISPLAYed. 


Chapter 6 - DATA DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 163 


6.9.9. BLANK 


( BLANK Attribute Syntax ] 


BLANK LINE|SCREEN 


This syntax is valid in the following sections: SCREEN 


This clause will blank out either the entire screen (BLANK SCREEN) or just the line upon 
which data is about to be displayed (BLANK LINE). 


1. Blanked-out areas will have their foreground and background colors set to the attributes 
of the field containing the BLANK clause. 


2. This clause is useful when one screen section item is being displayed over the top of a 
previously-displayed one. 
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6.9.10. BLANK WHEN ZERO 


( BLANK-WHEN-ZERO Attribute Syntax } 


BLANK WHEN ZERO 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 
This clause will cause that item’s value to be automatically transformed into spaces if a 
value of 0 is ever MOVEd to the item. 
1. The reserved word WHEN is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. 
2. This clause may only be used on a PIC 9 data item with a USAGE (see [USAGE], 
page 232) of DISPLAY. 
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6.9.11. BLINK 


( BLINK Attribute Syntax 


This syntax is valid in the following sections: SCREEN 


The BLINK clause modifies the visual appearance of the displayed field by making the 
field contents blink. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.12. COLUMN 


COLUMN (REPORT SECTION) Clause Syntax ] 


COLUMN [ { NUMBER IS }] [ +IPLUS ] integer-1 ] 


{ NUMBERS ARE } ais 


COLUMN (SCREEN SECTION) Clause Syntax ] 


COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ] 


This syntax is valid in the following sections: REPORT, SCREEN 


The COLUMN clause provides the means of stating in which column a field should be 


presented on the console window (screen section) or a report (report section). 


1. 


The reserved words ARE, IS, NUMBER and NUMBERS are optional and may be omitted. 
The presence or absence of these words has no effect upon the program. 


2. The reserved word COLUMN may be abbreviated as COL. 


3. The line location of a report section or screen section field will be determined by the 


LINE (see [LINE], page 183) clause. 


. The value of integer-1 must be 1 or greater. 


If identifier-1 is used to specify either an absolute or relative column position, identifier- 
1 must be defined as a numeric item of any USAGE (see [USAGE], page 232) other 
than COMPUTATIONAL-1 or COMPUTATIONAL-2, without editing symbols. The value of 
identifier-1 at the time the screen data item is presented must be 1 or greater. Note that 
a COMPUTATIONAL-1 or COMPUTATIONAL-2 identifier will be accepted by the compiler, 
but will produce unpredictable results at run-time. 


The column coordinate of a field may be stated on an absolute basis (i.e. COLUMN 5) 
or on a relative basis based upon the end of the previously-presented field (7.e. COLUMN 
PLUS 1). 


The symbol ‘+’ may be used in lieu of the word PLUS, if desired; if symbol ‘+’ is used, 

however, there must be at least one space separating it from integer-1. Failure to 

include this space will cause the symbol ‘+’ sign to be simply treated as part of integer- 

1 and will treat the COLUMN clause as an absolute column specification rather than a 

relative one. 

Using relative column positioning (COLUMN PLUS) has slightly different behaviour de- 

pending upon the section in which the clause is used, as follows: 

A. When used on a report section data item, COLUMN PLUS will position the start of 
the new field’s value such that there are integer-1 blank columns between the end 
of the previous field and the beginning of this field. 


Chapter 6 - DATA DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 167 


If a report data item’s description includes the SOURCE (see [SOURCE], page 215), 
SUM (see [SUM], page 516) or VALUE (see [VALUE], page 244) clause but has no 
COLUMN clause, COLUMN PLUS 1 will be assumed. 

B. When used on a screen section data item, COLUMN PLUS will position the new field 

so that it begins exactly integer-1 or identifier-1 characters past the last character 
of the previous field. Thus, COLUMN PLUS 1 will leave no blank positions between 
the end of the previous field and the start of this one. 
If a screen data item’s description includes the FROM (see [FROM], page 174), 
TO (see [TO], page 221), USING (see [USING], page 243) or VALUE (see [VALUE], 
page 244) clause but has no COLUMN clause, the new screen field will begin at the 
column coordinate of the last character of the previous field. 


15 January 2023 Chapter 6 - DATA DIVISION 


168 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


6.9.13. CONSTANT 


( CONSTANT Attribute Syntax j 


CONSTANT 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, SCREEN 
This option signifies that the 01-level data item in whose declaration CONSTANT is spec- 
ified will be treated as a symbolic name for a literal value, usable wherever a literal of the 
appropriate type could be used. 
1. The value of a data item defined as a constant cannot be changed at run-time. In fact, 
it is not syntactically acceptable to use such a data item as the destination field of any 
procedure division statement that stores a value. 


2. See [01-Level Constants], page 146, for additional information. 
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6.9.14. EMPTY-CHECK 


[ 


EMPTY-CHECK Attribute Syntax } 


EMPTY-CHECK 


This syntax is valid in the following sections: SCREEN 


This clause forces the user to enter data into the field it is specified on (or into all 


subordinate input-capable fields if EMPTY-CHECK is specified on a group item). 


1. The EMPTY-CHECK and REQUIRED (see [REQUIRED], page 206) clauses are interchange- 


able, and may not be used together in the same data item description. 


. In order to take effect, the user must first move the cursor into the field having this 


clause in its definition. 


. The ACCEPT data-item statement (see [ACCEPT data-item], page 272) will ignore the 


Enter key and any other cursor-moving keystrokes that would cause the cursor to move 
to another screen item unless data has been entered into the field. Function keys will 
still be allowed to terminate the ACCEPT. 


. In order to be functional, this attribute must be supported by the underlying “curses” 


package your GnuCOBOL implementation was built with. As of this time, the 
“PDCurses” package (used for native Windows or MinGW builds) does not support 
EMPTY-CHECK. 
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6.9.15. ERASE 


( ERASE Clause Syntax } 


ERASE EOL|EOS 


This syntax is valid in the following sections: SCREEN 


ERASE will blank-out screen contents from the location where the screen data item whose 
description contains this clause will be displayed, forward until the end of the screen (ERASE 
EOS) 


1. Erased areas will have their foreground and background colors set to the attributes of 
the field containing the ERASE clause. 


2. This clause is useful when one screen section item is being displayed over the top of a 
previously-displayed one. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.16. EXTERNAL 


( EXTERNAL Attribute Syntax 


EXTERNAL 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE 


This clause marks a data item description, FD or SD see [File/Sort-Description], page 124, 
as being shareable with other programs executed from the same execution thread. 

1. By specifying the EXTERNAL clause on either an FD or an SD, the file description is ca- 
pable of being shared between all programs executed from the same execution thread, 
provided an EXTERNAL clause is coded with the file’s description in each program re- 
quiring it. This sharing allows the file to be opened, read and/or written and closed in 
different programs. This sharing applies to the record descriptions subordinate to the 
file description too. 


2. By specifying the EXTERNAL clause on the description of a data item, the data item is 
capable of being shared between all programs executed from the same execution thread, 
provided the data item is coded (with an EXTERNAL clause) in each program requiring 
it. 

3. The following points apply to the specification of EXTERNAL in a data item’s definition: 
A. The EXTERNAL clause may only be specified at the 77 or 01 level. 

B. An EXTERNAL item must have a data name and that name cannot be FILLER. 


C. EXTERNAL cannot be combined with BASED (see [BASED], page 160), GLOBAL (see 
[GLOBAL], page 176) or REDEFINES (see [REDEFINES], page 204). 
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6.9.17. FALSE 


( FALSE Clause Syntax } 


WHEN SET TO FALSE IS literal-1 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 
This clause, which may only appear on the definition of a level-88 condition name, is 
used to specify the value of the data item that serves as the parent of the level-88 condition 
name that will force the condition name to assume a value of FALSE. 
1. The reserved words IS, SET, TO and WHEN are optional and may be omitted. The 
presence or absence of these words has no effect upon the program. 
2. See [88-Level Data Items], page 153, or See [Condition Names], page 45, for more 
information. 
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6.9.18. FOREGROUND-COLOR 


( FOREGROUND-COLOR Attribute Syntax } 


FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1 


This syntax is valid in the following sections: SCREEN 


This clause is used to specify the color of text within a screen data item or the default 
text color of subordinate items if used on a group item. 


1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. The reserved words FOREGROUND-COLOR and FOREGROUND-COLOUR are interchangeable. 


3. You specify colors by number (0-7), or by using the constant names provided in the 
screenio.cpy copybook (which is provided with all GnuCOBOL source distributions). 


4. Colors may also be specified using a numeric non-edited identifier whose value is in the 
range 0-7. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 


15 January 2023 Chapter 6 - DATA DIVISION 


174 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


6.9.19. FROM 


( FROM Clause Syntax } 


FROM literal-1 | identifier-5 


This syntax is valid in the following sections: SCREEN 


This clause is used to specify either the data item a screen section field is to obtain its 
value from when the screen is displayed, or a literal that will specify the value of that same 
field. 

1. The FROM, TO (see [TO], page 221), USING (see [USING], page 243) and VALUE (see 
[VALUE], page 244) clauses are mutually-exclusive in any screen section data item’s 
definition. 
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6.9.20. FULL 


( FULL Attribute Syntax } 


This syntax is valid in the following sections: SCREEN 

The FULL clause forces the user to enter data into the field it is specified on (or into all 
subordinate input-capable fields if specified on a group item) sufficient to fill every character 
position of the field. 

1. The FULL and LENGTH-CHECK (see [LENGTH-CHECK], page 182) clauses are inter- 
changeable, and may not be used together in the same data item description. 

2. In order for this clause to take effect at execution time, the user must move the cursor 
into the field having this clause in its definition. 

3. The ACCEPT data-item statement (see [ACCEPT data-item], page 272) will ignore the 
Enter key and any other cursor-moving keystrokes that would cause the cursor to move 
to another screen item unless the proper amount of data has been entered into the 
field. Function keys will still be allowed to terminate the ACCEPT, however. 

4. In order to be functional, this attribute must be supported by the underlying “curses” 
package your GnuCOBOL implementation was built with. As of this time, the “PD- 
Curses” package (used for native Windows or MinGW builds) does not support FULL. 


15 January 2023 Chapter 6 - DATA DIVISION 


176 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


6.9.21. GLOBAL 


[ 


GLOBAL Attribute Syntax j 


GLOBAL 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
REPORT 


This clause marks a data item, Ql-level constant, FD (see [File/Sort-Description], 


page 124), SD (see [File/Sort-Description], page 124) or an RD (see [REPORT SECTION], 
page 135) as being shareable with any nested subprograms. 


1. By specifying the GLOBAL clause on the description of a file or a report, that description 


is capable of being shared between a program and any nested subprograms within it, 
provided the FD, SD or RD is coded (with a GLOBAL clause) in each nested subprogram 
requiring it. This sharing allows the file to be opened, read and/or written and closed 
or the report to be initiated or terminated in those programs. Separately compiled 
programs may not share a GLOBAL file description, but they may share an EXTERNAL 
(see [EXTERNAL], page 171) file description. This sharing applies to the record de- 
scriptions subordinate to the file description and the report groups subordinate to the 
RD also. 


. By specifying the GLOBAL clause on the description of a data item, the data item is 


capable of being shared between a program and any nested subprograms within it, 
provided the data item is coded (with a GLOBAL clause) in each program requiring it. 


3. The following points apply to the specification of GLOBAL in a data item’s definition: 


A. The GLOBAL clause may only be specified at the 77 or 01 level. 
B. A GLOBAL item must have a data name and that name cannot be FILLER. 


C. GLOBAL cannot be combined with EXTERNAL (see [EXTERNAL], page 171), 
REDEFINES (see [REDEFINES], page 204) or BASED (see [BASED], page 160). 
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6.9.22. GROUP INDICATE 


( GROUP-INDICATE Attribute Syntax 


GROUP INDICATE 


This syntax is valid in the following sections: REPORT 


The GROUP INDICATE clause specifies that the data item in whose definition the clause 
appears will be presented only in very limited circumstances. 


1. This clause may only appear within a DETAIL report group (see [TYPE], page 222). 


2. When this clause is present, the data item in question will be presented only under the 
following circumstances: 


A. On the first presentation of the detail group following the INITIATE (see 
[INITIATE], page 343) of the report. 


B. On the first presentation of the detail group after every new page is started. 


C. On the first presentation of the detail group after any control break occurs. 
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6.9.23. HIGHLIGHT 


( HIGHLIGHT Attribute Syntax 


HIGHLIGHT 


This syntax is valid in the following sections: SCREEN 


This clause controls the intensity of text (FOREGROUND-COLOR (see [FOREGROUND- 
COLOR], page 173)) by setting that intensity to its highest of three possible settings. 


1. This clause, along with LOWLIGHT (see [LOWLIGHT], page 186), are intended to provide 
a three-level intensity scheme (LOWLIGHT ... nothing (Normal) ... HIGHLIGHT). 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.24. JUSTIFIED 


[ 


JUSTIFIED Attribute Syntax } 


JUSTIFIED RIGHT 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 


The presence of a JUSTIFIED RIGHT clause in a data item’s definition alters the manner 


in which data is stored into the field from the default ’left-justified, space filled’ behaviour 
to ’right justified, space filled’. 


1. 


The reserved word RIGHT is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. 


The reserved word JUSTIFIED may be abbreviated as JUST. 
This clause is valid only on alphabetic (PIC A) or alphanumeric (PIC X) data items. 


The presence or absence of this clause influences the behaviour of the MOVE (see 
[MOVE], page 352) statement as well as the FROM (see [FROM], page 174), SOURCE 
(see [SOURCE], page 215) and USING (see [USING], page 243) data item description 
clauses. 


If the value being stored into the field is the same length as the receiving field, the 
presence or absence of the JUSTIFIED RIGHT clause on that field’s description is irrele- 
vant. 


The following examples illustrate the behaviour of the presence and absence of the 
JUSTIFIED RIGHT clause when the field size is different than that of the value being 
stored. In these examples, the symbol 6 represents a space. 


ve 


When the value is shorter than the field size: 

Without JUSTIFIED With JUSTIFIED 

O1 <A PIC X(6). 01 A PIC X(6) JUSTIFIED RIGHT. 
MOVE @code{ABC} TO A MOVE @code{ABC} TO A 

Result Result 

ABCbbb bbbABC 
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( >) 
When the value is longer than the field size: 
Without JUSTIFIED With JUSTIFIED 
O1 <A PIC X(6). O1 A PIC X(6) JUSTIFIED RIGHT. 
MOVE ’ABCDEFGHI’ TO A MOVE ’ABCDEFGHI’ TO A 
Result Result 
ABCDEF DEFGHI 
ZY 
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6.9.25. LEFTLINE 


( LEFTLINE Attribute Syntax } 


LEFTLINE 


This syntax is valid in the following sections: SCREEN 
The LEFTLINE clause will introduce a vertical line at the left edge of a screen field. 

1. The LEFTLINE, OVERLINE (see [OVERLINE], page 193) and UNDERLINE (see 
[UNDERLINE], page 229) clauses may be used in any combination in a single field’s 
description. 

2. This clause is essentially non-functional when used within Windows command shell 
(cmd.exe) environments and running programs compiled using a GnuCOBOL imple- 
mentation built using “PDCurses” (such as Windows/MinGW builds). 

3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will 
depend upon the video attribute capabilities of the terminal output drivers and “curses” 
software being used. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.26. LENGTH-CHECK 


[ 


LENGTH-CHECK Attribute Syntax } 


LENGTH-CHECK 


This syntax is valid in the following sections: SCREEN 


The LENGTH-CHECK clause forces the user to enter data into the field it is specified on (or 


into all subordinate input-capable fields if specified on a group item) sufficient to fill every 
character position of the field. 


1. The FULL (see [FULL], page 175) and LENGTH-CHECK clauses are interchangeable, and 


may not be used together in the same data item description. 


. In order for this clause to take effect at execution time, the user must move the cursor 


into the field having this clause in its definition. 


. The ACCEPT data-item statement (see [ACCEPT data-item], page 272) will ignore the 


Enter key and any other cursor-moving keystrokes that would cause the cursor to move 
to another screen item unless the proper amount of data has been entered into the 
field. Function keys will still be allowed to terminate the ACCEPT, however. 


. In order to be functional, this attribute must be supported by the underlying “curses” 


package your GnuCOBOL implementation was built with. As of this time, the 
“PDCurses” package (used for native Windows or MinGW builds) does not support 
LENGTH-CHECK. 
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6.9.27. LINE 


LINE (REPORT SECTION) Clause Syntax 


LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } 
= ge MO ee eg Fen Sarg } 
{ +|PLUS integer-2 } 

; eres } 

} 


{ ON NEXT PAGE 


LINE (SCREEN SECTION) Clause Syntax 


[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ] 


This syntax is valid in the following sections: REPORT, SCREEN 
This clause provides a means of explicitly stating on which line a field should be presented 
on the console window (screen section) or on a report (report section). 
1. The reserved words IS, NUMBER and ON are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 
2. The following points document the use of format 1 of the LINE clause: 


A. The column location of a report item will be determined by the COLUMN (see 
[COLUMN], page 166) clause. 

B. The value of integer-1 must be 1 or greater. 

C. The report line number upon which the data item containing this clause along 
with any subordinate data items will be presented may be stated on an absolute 
basis (i.e. LINE 5) or on a relative basis based upon the previously-displayed line 
(i.e. LINE PLUS 1). 

D. The symbol ‘+’ may be used in lieu of the word PLUS, if desired; if ‘+’ is used, 
however, there must be at least one space separating it from integer-1. Failure to 
include this space will cause the ‘+’ to be simply treated as part of integer-1 and 
will treat the LINE clause as an absolute line specification rather than a relative 
one. 

E. The optional NEXT PAGE clause specifies that — regardless of whether or not the 
report group containing this clause could fit on the report page being currently 
generated, the report group will be forced to appear on a new page. 

3. The following points document the use for format 2 of the LINE clause: 


A. The column location of a screen section field is determined by the COLUMN (see 
[COLUMN], page 166) clause. 
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. The value of integer-1 must be 1 or greater. 


. If identifier-1 is used to specify either an absolute or relative column position, 


identifier-1 must be defined as a numeric item of any USAGE (see [USAGE], 
page 232) other than COMPUTATIONAL-1 or COMPUTATIONAL-2, without editing 
symbols. The value of identifier-1 at the time the screen data item is presented 
must be 1 or greater. Note that a COMPUTATIONAL-1 or COMPUTATIONAL-2 
identifier will be accepted by the compiler, but will produce unpredictable results 
at run-time. 


. The screen line number upon which the data item containing this clause along 


with any subordinate data items will be displayed may be stated on an absolute 
basis (i.e. LINE 5) or on a relative basis based upon the previously-displayed line 
(i.e. LINE PLUS 1). 


. The symbol ‘+’ may be used in lieu of the word PLUS, if desired; if ‘+’ is used, 


however, there must be at least one space separating it from integer-1. Failure to 
include this space will cause the ‘+’ to be simply treated as part of integer-1 and 
will treat the LINE clause as an absolute line specification rather than a relative 
one. 


. If a screen data item’s description includes the FROM (see [FROM], page 174), 


TO (see [TO], page 221), USING (see [USING], page 243) or VALUE (see [VALUE], 
page 244) clause but has no LINE clause, the “current screen line” will be assumed. 
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6.9.27B. LOWER 


( LOWER Attribute Syntax 


This syntax is valid in the following sections: SCREEN 


This clause provides a means of explicitly stating that accepted data will be in lower 
case. 
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6.9.28. LOWLIGHT 


( LOWLIGHT Attribute Syntax 


LOWLIGHT 


This syntax is valid in the following sections: SCREEN 
The LOWLIGHT clause controls the intensity of text (FOREGROUND-COLOR) by setting that 
intensity to its lowest of three possible settings. 
1. This clause, along with HIGHLIGHT (see [HIGHLIGHT], page 178), are intended to pro- 
vide a three-level intensity scheme (LOWLIGHT ... nothing (Normal) ... HIGHLIGHT). 
In environments such as a Windows console where only two levels of intensity are 
supported, LOWLIGHT is the same as leaving this clause off altogether. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.29. NEXT GROUP 


187 


( NEXT-GROUP Clause Syntax 


NEXT GROUP IS { [ +IPLUS ] integer-2 } 
ne aN ag { ee i: 
{ NEXT|{NEXT PAGE}|PAGE } 


This syntax is valid in the following sections: REPORT 


This clause defines any rules for where the next group to be presented on a report will 


begin, line-wise, with respect to the last line of the group in which this clause appears. 


1. The reserved word IS is optional and may be omitted. The presence or absence of this 


word has no effect upon the program. 
2. The terms NEXT, NEXT PAGE and PAGE are interchangeable. 


3. A report group must contain at least one LINE NUMBER clause in order to also contain 


a NEXT GROUP clause. 


4. If the RD (see [REPORT SECTION], page 135) in which the report group containing 
a NEXT GROUP clause does not contain a PAGE LIMITS clause, only the PLUS integer-1 


option may be specified. 
5. The NEXT PAGE option cannot be used in a PAGE FOOTING. 


6. The NEXT GROUP option cannot be specified in either a REPORT HEADING or a PAGE 


HEADING. 


7. The effects of NEXT GROUP will be in addition to any line spacing defined by the next- 


presented group’s LINE NUMBER clause. 
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6.9.30. NO-ECHO 


( NO-ECHO Attribute Syntax 


NO-ECHO 


This syntax is valid in the following sections: SCREEN 


The NO-ECHO clause will cause all data entered into the field to appear on the screen as 
asterisks. 


1. The NO-ECHO and SECURE (see [SECURE], page 212) clauses are interchangeable, and 
may not be used together in the same data item description. 


2. This clause may only be used on a field allowing data entry (a field containing either 
the USING (see [USING], page 243) or TO (see [TO], page 221) clause). 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.30B. NO UPDATE 


( NO-UPDATE Attribute Syntax 


NO UPDATE 


This syntax is valid in the following sections: SCREEN 


The NO UPDATE clause forces the field to which this is applied will not be updated 
MORE?’?. 
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6.9.31. OCCURS 


( OCCURS Clause Syntax 


GENERAL FORMAT. 
Format 1 (fixed-table): 


OCCURS integer-2 TIMES 


Format 2 (occurs-depending-table): 


OCCURS [ integer-1 TO ] { integer-2 TIMES } [ DEPENDING ON identifier-1 ] 
Me ~~ { UNBOUNDED : ae 


[ ASCENDING|DESCENDING KEY IS identifier-5 ... ] 


REPORT SECTION. 


Format 3 


[ STEP integer-3 ] 


[ VARYING identifier-2 FROM { identifier-3 } BY { identifier-4 } ] 
cick: ~~~~ { integer-4 } ~~ { integer-5 } 
SCREEN SECTION. 
Format 4 


OCCURS integer-2 TIMES 
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This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 


The OCCURS clause is used to create a data structure called a table, where entries in that 
structure repeat multiple times. 


1. The reserved words BY (INDEXED), IS, KEY, ON and TIMES are optional and may be 
omitted. The presence or absence of these words has no effect upon the program. 
2. The value of integer-2 specifies how many entries will be allocated in the table. 
3. The following is an example of how a table might be defined: 
05 QUARTERLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99. 
This will allocate the following: 


QUARTERLY-REVENUE (1) 
QUARTERLY-REVENUE (2) 
QUARTERLY-REVENUE (3) 
QUARTERLY-REVENUE (4) 


Each occurrence is referenced using the subscript syntax (a numeric literal, arithmetic 
expression or numeric identifier enclosed within parenthesis) shown above. 


4. The OCCURS clause may be used at the group level too, in which case the entire group 
structure repeats, as follows: 


05 GRP OCCURS 3 TIMES. 


10 A PIC X(1). 
10 B PIC X(1). 
10 C PIC X(1). 


This would allow references to any of the following: 


GRP(1) includes A(1), B(1) and C(1) 
GRP(2) includes A(2), B(2) and C(2) 
GRP(3) includes A(3), B(3) and C(3) 


or each A,B,C item could be referenced as follows: 


A(1) character #1 of GRP(1) 
B(1) character #2 of GRP(1) 
C(1) character #3 of GRP(1) 
A(2) — character #1 of GRP(2) 
B(2) character #2 of GRP(2) 
C(2) character #3 of GRP(2) 
A(3) character #1 of GRP(3) 
B(3) character #2 of GRP(3) 
C(3) character #3 of GRP(3) 


5. The optional DEPENDING ON clause can be added to an OCCURS to create a variable- 
length table. In such cases, the value of integer-1 specifies what the minimum number 
of entries in the table will be while integer-2 specifies the maximum. Such tables will 
be allocated out to the maximum size specified as integer-2. At execution time the 
value of identifier-1 will determine how many of the table elements are accessible. 
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6. See the documentation of the SEARCH (see [SEARCH], page 377), SEARCH ALL (see 
[SEARCH ALL], page 379) and SORT (see [SORT], page 391) statements for explana- 
tions of the KEY and INDEXED BY clauses. 


7. The OCCURS clause cannot be specified in a data description entry that has a level 
number of 01, 66, 77, or 88, although it is valid in data items described subordinate to 
an O1-level data item. 


8. The following points apply to an OCCURS used in the report section: 


A. The optional STEP clause defines an incrementation value that will be added to any 
absolute LINE (see [LINE], page 183) or COLUMN (see [COLUMN], page 166) number 
specifications that may be part of or subordinate to this data item’s definition. 


B. The optional VARYING clause defines an identifier that may be used as a sub- 
script for the multiple occurrences of this or any subordinate data item should the 
SOURCE (see [SOURCE], page 215) or SUM (see [SUM], page 516) clause(s) on this 
or subordinate data items reference entries within the table. The identifier-2 data 
item is dynamically created as needed and cannot be referenced outside the scope 
of the report data item definition. 

C. The following two examples illustrate two different ways a report could include 
four quarters worth of sales figures in its detail lines — one doing things ’the hard 
way’ and one using the advanced OCCURS capabilities of STEP and VARYING. Both 
assume the definition of the following table exists in working-storage: 

05 SALES OCCURS 4 TIMES PIC 9(7)V99. 
First, the “Hard Way”: 
10 COL 7 PIC $(7)9.99 SOURCE SALES(1). 
10 COL 17 PIC $(7)9.99 SOURCE SALES(2). 
10 COL 27 PIC $(7)9.99 SOURCE SALES(3). 
10 COL 37 PIC $(7)9.99 SOURCE SALES (4). 
And then using STEP and VARYING: 


10 COL 7 OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1 
PIC $(7)9.99 SOURCE SALES (QTR) . 
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6.9.32. OVERLINE 


( OVERLINE Attribute Syntax } 


OVERLINE 


This syntax is valid in the following sections: SCREEN 
The OVERLINE clause will introduce a horizontal line at the top edge of a screen field. 

1. The LEFTLINE (see [LEFTLINE], page 181), OVERLINE and UNDERLINE (see 
[UNDERLINE], page 229) clauses may be used in any combination in a single field’s 
description. 

2. This clause is essentially non-functional when used within Windows command shell 
(cmd.exe) environments and running programs compiled using a GnuCOBOL imple- 
mentation built using “PDCurses” (such as Windows/MinGW builds). 

3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will 
depend upon the video attribute capabilities of the terminal output drivers and “curses” 
software being used. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.33. PICTURE 


[ 


PICTURE Clause Syntax 


PICTURE IS picture-string 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 


The picture clause defines the class (numeric, alphabetic or alphanumeric), size and 
format of the data that may be contained by the data item being defined. Sometimes this 
role is assisted by the USAGE (see [USAGE], page 232) clause, and in a few instances will be 
assumed entirely by that clause. 


1. 


The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


The reserved word PICTURE may be abbreviated as PIC. Most programmers prefer to 
use the latter. 


3. A picture clause may only be specified on an elementary item. 


4. A picture-string is a sequence of the special symbols ‘$’, ‘*’, ‘+’, £,’, ‘-’, £.’, ‘7’, ‘0’ 


(zero), ‘17; 9", *A’, “B’, CR, DB, *S’, °V’, “X? and. *2’. 
In general, each picture symbol represents either a single character in storage or a single 
decimal digit. There are a few exceptions, and they will be discussed as needed. 


When a picture-string contains a repeated sequence of symbols — PIC 9999/99/99 
— for example, the repetition can be specified using a parenthetic repeat count, as 
in PIC 9(4)/9(2)/9(2). Using repeat counts is optional and their use (or not) is 
entirely at the discretion of the programmer. Many programmers use repetition for 
small sequences (PIC XXX) and repeat counts for larger ones (PIC 9(9). 


This first set of picture symbols defines the basic data type of a data item. Each symbol 
represents a single character’s worth of storage. 


‘NW’ Defines storage reserved for a single alphabetic character (‘A’-‘Z’, ‘a’-‘z’). 


‘N’ Defines storage reserved for a single character in the computer’s National 
Character set. Support for national character sets in GnuCOBOL is cur- 
rently only partially implemented, and the compile- and run-time effect 
of using the ‘N’ picture symbol is the same as if X(2) had been coded, 
with the additional effect that such a field will qualify as a NATIONAL or 
NATIONAL-EDITED field on an INITIALIZE (see [INITIALIZE], page 339) 


statement. 

‘x’ Defines storage reserved for a single alphanumeric character (any charac- 
ter). 

‘9’ Defines storage reserved for a single numeric digit character (‘0’-‘9’). 
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Typically, only one kind of each of those symbols is used in the same picture clause, 
but that isn’t a requirement. Data items that, of the three symbols above, use nothing 
but ‘A’ picture symbols are known as Alphabetic Data Items while those that use ‘9’ 
picture symbols without any ‘A’ or ‘X’ symbols (or those that have a USAGE without a 
PICTURE) are known as Numeric Data Items. All other data items are referred to as 
Alphanumeric Data Items. 


If you need to allocate space for a data item whose format is two letters followed 
by five digits followed by three letters, you could use the picture-string AAQQ999AAA, 
A(2)9(5)A(3) XXXXXXXXXX or X(10). There is absolutely no functional difference what- 
soever between the four — none of them provide any functionality the others do not. 
The first two probably make for better documentation of the expected field contents, 
but they don’t provide any run-time enforcement capabilities. 


As far as enforcement goes, however, both alphabetic and numeric picture strings do 
provide for both compile-time and run-time enforcement capabilities. In the case of 
compilation enforcement, the compiler can issue warning messages if you attempt to 
specify a non-numeric value for a numeric data item or if you attempt to MOVE (see 
[MOVE], page 352) a non-numeric data item to one that is numeric. Similar capabilities 
exist for alphabetic data items. At run-time, you may use a special class test (see [Class 
Conditions], page 46) to determine if the contents of a data item are entirely numeric 
or entirely alphabetic. 


8. ‘1’ Defines storage for a single bit representing a boolean condition with a states of 
zero or 1, condition of off or on. Warning the level of implementation of this feature is 
compiler version specific starting with v3.1-RC-1. 


9. The following picture symbols may be used with numeric data items. 


‘p’ Defines an implied digit position that will be considered to be a zero when 
the data item is referenced at run-time. This symbol is used to allow data 
items that will contain very large values to be allocated using less storage 
by assuming a certain number of trailing zeros (one per ‘P’) to exist at the 
end of values. 


The ‘P’ symbol is not allowed in conjunction with ‘N’. 


The ‘P’ symbol may only be used at the beginning or end of a picture 
clause. 

‘P’ is a repeatable symbol. 

All computations and MOVE (see [MOVE], page 352) operations involving 
such a data item will behave as if the zeros were actually there. 

For example, let’s say you need to allocate a data item that contains how- 
ever many millions of dollars of revenue your company has in gross revenues 
this year: 

01 Gross-Revenue PIC 9(9). 

In which case 9 characters of storage will be reserved. The values 000000000 
through 999999999 will represent the gross-revenues. But, if only the mil- 


lions are tracked (meaning the last six digits are always going to be 0), you 
could define the field as: 
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01 Gross-Revenue PIC 9(3)P(6). 


Whenever Gross-Revenue is referenced in calculations, or whenever its 
value is moved to another data item, the value of Gross-Revenue will be 
treated as if it is nnn000000, where nnn is the actual value in storage. 


If you wanted to store the value 128 million into that field, you would do 
so as if the ‘P’s were ‘9’s: 


MOVE 128000000 TO Gross-Revenue 


A DISPLAY (see [DISPLAY], page 305) of a data item containing ‘P’ symbols 
is a little strange. The value displayed will be what is actually in storage, 
but the total size of the displayed value will be as if the ‘P’ symbols had 
been ‘9’s. Thus, after the above statement established a value for Gross- 
Revenue, a DISPLAY Gross-Revenue would produce output of ‘000000128’. 


This symbol, if used, must be the very first symbol in the PICTURE value. A 
‘S’ indicates that the data item is Signed, meaning that negative values are 
possible for this data item. Without an ‘S’, any negative values stored into 
this data item via a MOVE or arithmetic statement will have the negative 
sign stripped from it (in effect becoming the absolute value). 


The ‘S’ symbol is not allowed in conjunction with ‘N’. 


The ‘S’ symbol may only occur once in a picture string. See [SIGN IS], 
page 213, for further discussion of how negative values may be stored in a 
numeric data item. 


This symbol is used to define where an implied decimal-point (if any) is 
located in a numeric item. Just as there may only be a single decimal point 
in a number so may there be no more than one ‘V’ in a PICTURE. Implied 
decimal points occupy no space in storage — they just specify how values 
are used. For example, if the value 1234 is in storage in a field defined as 
PIC 999V9, that value would be treated as 123.4 in any statements that 
referenced it. 


The ‘V’ symbol is not allowed in conjunction with ‘N’. 


The ‘V’ symbol may only occur once in a picture string. 


10. Any editing symbols introduced past this point will, if coded in the picture clause of an 


11. 


otherwise numeric data item, transform that data item from a numeric to a Numeric 
Edited data item. Numeric edited data items are treated as alphanumeric and may not 
serve either as table subscripts or as source arguments on an arithmetic statement. 


The following are the fixed insertion editing symbols that may be specified in a picture 
string. Each of these editing symbols will insert a special character into the field value 


at the position it is specified in the picture string. These editing symbols will each 


‘p? 


introduce one extra character into the total field size for each occurrence of the symbol 
in the picture string. 


The ‘B’ editing symbol introduces a blank into the field value for each 
occurrence. 


Multiple ‘B’ symbols may be coded. 
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The following example will format a ten digit number (presumably a tele- 
phone number) into a ‘### ### #### layout: 


05 Phone-Number PIC 9(3)B9(3)B9(4). 


MOVE 5185551212 TO Phone-Number 
DISPLAY Phone-Number 


This code will display ‘518 555 1212’. 


‘0’ The ‘0’ (zero) editing symbol introduces one “0” character into the field 
value for each occurrence in the picture string. 


Multiple ‘0’ symbols may be coded. 


Here’s an example: 


05 Output-Item PIC 909090909. 


MOVE 12345 TO Output-Item 
DISPLAY Output-Item 


The above will display ‘102030405’. 


‘7. The ‘/’ editing symbol inserts one “/” character into the field value for 
each occurrence in the picture string. 


Multiple ‘/’ symbols may be coded. 


This editing symbol is most-frequently used to format dates, as follows: 


05 Year-Month-Day PIC 9(4)/9(2)/9(2). 


MOVE 20140207 TO Year-Month-Day 
DISPLAY Year-Month-Day 


This example displays ‘2014/02/07’. 


12. The following are the numeric formatting symbols that may be specified in a picture 
string. Each of these editing symbols will insert special characters into the field value to 
present numbers in a “friendly” format. These editing symbols will each introduce one 
extra character into the total field size for each occurrence of the symbol in the picture 
string. Numeric fields whose picture clause contains these characters may neither be 
used as source fields in any calculation nor may they serve as source fields for the 
transfer of data values to any data item other than an alphanumeric field. 


nh The ‘.’ symbol inserts a decimal point into a numeric field value. When 
the contents of a numeric data item sending field are moved into a receiving 
data item whose picture clause contains the ‘.’ editing symbol, implied (‘V’) 
or actual decimal point in the sending data item or literal, respectively, 
will be aligned with the ‘.’ symbol in the receiving field. Digits are then 
transferred from the sending to the receiving field outward from the sending 
field’s ‘V’ or ‘.’, truncating sending digits if there aren’t enough positions 
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in the receiving field. Any digit positions in the receiving field that don’t 
receive digits from the sending field, if any, will be set to 0. 


The ‘.’ symbol is not allowed in conjunction with ‘N’. 


An example will probably help: 


05 Source-Field PIC 9(2)V9 VALUE 7.2. 
05 Dest-Field PIC 9(5).9(2). 


MOVE 1234567.89 TO Dest-Field 
DISPLAY Dest-Field 

MOVE 19 TO Dest-Field 

DISPLAY Dest-Field 

MOVE Source-Field TO Dest-Field 
DISPLAY Dest-Field 


The example will display three results — ‘34567.89’, ‘00019.00’ and 
‘00007 .20’. 


Both data item definitions appear to have two decimal points in their pic- 
ture clauses. They actually don’t, because the last character of every data 
item definition is always a period — the period that ends the definition. 


; The ‘,’ symbol serves as a thousands separator. Many times, you'll see 
large numbers formatted with these symbols — for example, 123,456,789. 
This can be accomplished easily by adding thousands separator symbols 
to a picture string. Thousands separator symbols that aren’t needed will 
behave as if they were ‘9’s. 


The ‘,’ symbol is not allowed in conjunction with ‘N’. 


Here’s an example: 


05 My-Lottery-Winnings PIC 9(3),9(3),9(3). 


MOVE 12345 TO My-Lottery-Winnings 

DISPLAY My-Lottery-Winnings 
The value ‘0000012, 345’ (a very disappointing one for my retirement plans, 
but a good thousands separator demo) will be displayed. Notice how, since 
the first comma wasn’t needed due to the meagre amount I won, it behaved 
like another ‘9’. 


If desired, you may reverse the roles of the ‘.’ and ‘,’ editing symbols by specifying 
DECIMAL POINT IS COMMA in the SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) 
paragraph. 

The following are insertion symbols. They are used to insert an extra character (two 
in the case of CR and DB) to signify the sign (positive or negative) of the numeric value 
that is moved into the field whose picture string contains one of these symbols, or the 
fact that the data item represents a currency (money) amount. Only one of the ‘+’, 
‘—’ CR or DB symbols may be used in a picture clause. In this context, when any of 
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these symbols are used in a picture-string, they must be at the end. The ‘+’, ‘-’ and/or 
currency symbols may also be used as floating editing symbols at the beginning of the 
picture-string — a subject that will be covered in the next numbered paragraph. 


oy? 


CR 


DB 


If the value of the numeric value moved into the field is positive (0 or 
greater), a ‘+’ character will be inserted. If the value is negative (less than 
0), a ‘-’ character is inserted. 


The ‘+’ symbol is not allowed in conjunction with ‘N’. 


If the value of the numeric value moved into the field is positive (0 or 
greater), a space will be inserted. If the value is negative (less than 0), a 
‘—’ character is inserted. 


The ‘-’ symbol is not allowed in conjunction with ‘N’. 


This symbol is coded as the two characters ‘C’ and ‘R’. If the value of the 
numeric value moved into the field is positive (0 or greater), two spaces 
will be inserted. If the value is negative (less than 0), the characters CR 
(credit) are inserted. 


The CR symbol is not allowed in conjunction with ‘N’. 
This symbol is coded as the two characters ‘D’ and ‘B’. If the value of the 
numeric value moved into the field is positive (0 or greater), two spaces 


will be inserted. If the value is negative (less than 0), the characters DB 
(debit) are inserted. 


The DB symbol is not allowed in conjunction with ‘N’. 


Regardless of the value moved into the field, this symbol will insert the 
currency symbol into the data item’s value in the position where it occurs 
in the picture-string (see |SPECIAL-NAMES], page 92). 


The ‘$’ symbol is not allowed in conjunction with ‘N’. 


14. These editing symbols are known as floating replacement symbols. These symbols may 
occur in sequences before any ‘9’ editing symbols in the picture-string of a numeric 
data item. Using these symbols transforms that numeric data item into a numerid 
edited data item, which can no longer be used in calculations or subscripts. 


15. Each of the following symbols behave like a ‘9’, until such point as all digits in the 
numeric value are exhausted and leading zeros are about to be inserted. In effect, these 
editing symbols define what should happen to those leading zero. 


ig? 


15 January 2023 


Of those currency symbols that correspond to character positions in which 
leading zeros reside, the right-most will have its ‘0’ value replaced by 
the currency symbol in-effect for the program (see [SPECIAL-NAMES], 
page 92). Any remaining leading zero values occupying positions described 
by this symbol will be replaced by spaces. 

The ‘$’ symbol is not allowed in conjunction with ‘N’. 


Any currency symbol coded to the right of a ‘.’ will be treated exactly like 
a ‘9’, 
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‘x? This symbol is referred to as a check protection symbol. All check- 
protection symbols that correspond to character positions in which 
leading zeros reside will have their ‘0’ values replaced by ‘*’. 


The ‘*’ symbol is not allowed in conjunction with ‘N’. 


Any check-suppression symbol coded to the right of a ‘.’ will be treated 
exactly like a ‘9’. 


“oe? Of those ‘+’ symbols that correspond to character positions in which leading 
zeros reside, the right-most will have its ‘0’ value replaced by a ‘+’ if the 
value in the data item is zero or greater or a ‘-’ otherwise. Any remaining 
leading zero values occupying positions described by this symbol will be 
replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same picture- 
string. 

The ‘+’ symbol is not allowed in conjunction with ‘N’. 


Any ‘+’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’. 


Of those ‘-’ symbols that correspond to character positions in which leading 
zeros reside, the right-most will have its ‘0’ value replaced by a space if the 
value in the data item is zero or greater or a ‘-’ otherwise. Any remaining 
leading zero values occupying positions described by this symbol will be 
replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same picture- 
string. 

The ‘-’ symbol is not allowed in conjunction with ‘N’. 


Any ‘-’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’. 


‘Z’ All ‘Z’ symbols that correspond to character positions in which leading 
zeros reside will have their ‘0’ values replaced by spaces. 


Any zero-suppression symbol coded to the right of a ‘.’ will be treated 
exactly like a ‘9’. 


‘Z’ and ‘*’ should not be coded in the same picture-string 
‘+’ and ‘-’ should not be coded in the same picture-string 


When multiple floating symbols are coded, even if there is only one of them used they 
will all be considered floating and will all be able to assume each other’s properties. 
For example, if a data item has a PIC +$ZZZZ9.99 picture-string, and a value of 1 is 
moved to that field at run-time, the resulting value will be (the b symbol represents a 
space) bbbb+$1.00. This is not consistent with many other COBOL implementations, 
where the result would have been +$bbbb1 .00. 

Most other COBOL implementations reject the use of multiple occurrences of multi- 
ple floating editing symbols. For example, they would reject picture-strings such as 
+++$$$9.99, $$$ZZZ9.99 and so on. GnuCOBOL accepts these. Programmers creat- 
ing GnuCOBOL programs should avoid such picture-strings if there is any likelihood 
that those programs may be used with other COBOL implementations. 
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6.9.34. PRESENT WHEN 


( PRESENT-WHEN Clause Syntax } 


PRESENT WHEN condition-name 


This syntax is valid in the following sections: REPORT 


This clause names an existing Condition Name (see [Condition Names], page 45) that 
will serve as a switch controlling the presentation or suppression of a report group. 


1. If the specified condition-name has a value of FALSE when a GENERATE statement (see 
[GENERATE], page 332) causes a report group to be presented, the presentation of 
that group will be suppressed. 


2. If the condition-name has a value of TRUE, the group will be presented. 


3. See [Condition Names], page 45, for more information. 
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6.9.35. PROMPT 


( PROMPT Clause Syntax 


PROMPT [ CHARACTER IS literal-1 | identifier-1 ] 


This syntax is valid in the following sections: SCREEN 


This clause defines the character that will be used as the fill-character for any input 
fields on the screen. 


1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. The default prompt character, should no CHARACTER specification be coded, or should 
the PROMPT clause be absent altogether, is an underscore (‘_’). 


3. Prompt characters will be automatically transformed into spaces upon input. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.36. PROTECTED 


( PROTECTED Attribute Syntax 


PROTECTED SIZE IS { identifier } 
Ta ORT ANS aaa { integer } 


This syntax is valid in the following sections: SCREEN 


The PROTECTED extended clause will effect the specified field to be limited in size, 
regardless of the picture size.! 


1. The SIZE phrase specifies the size (length) of the field. After the ACCEPT or DISPLAY is 
finished, the cursor is placed immediately after the field defined by this clause, unless 
this would place the cursor outside of the current terminal window. In this case, the 
cursor is wrapped around to the beginning of the next line (scrolling the window if 
necessary). 


2. If the SIZE phrase is not used, then the field length defaults to the size of the item 
being accepted or displayed. If the CONVERT phrase is used, however, then the size of 
the field depends on the data type of the item and the verb being used. 


A. If the DISPLAY verb is executing, then the size is the same as if the CONVERT 
phrase were not specified except for numeric items. For numeric items, the size is 
the number of digits in the item, plus one if it is not an integer, plus one if it is 
signed. The remaining cases cover the size when an ACCEPT statement is used. 


B. If the item is numeric or numeric edited, then the size is the number of digits in 
the item, plus one if it is not an integer, plus one if it is signed. 


C. If the item is alphanumeric edited, then the size is set to the number of ‘A’ or ‘X’ 
positions specified in its PICTURE clause. 


D. For all other data types, the field size is set to the size of the item (same as if 
CONVERT were not specified). 


3. Note that the OUTPUT phrase changes the way in which the default field size is computed. 
See that heading above for details. Also note that the OUTPUT phrase affects only the 
way items are displayed on the screen; the internal format of accepted data is not 
affected. 

4. Note that you cannot supply the CONVERT phrase in the Screen Section. Thus the size 
of a Screen Section field is always the size of its screen entry unless the SIZE phrase is 
specified. 


! OR DOES IT? author uncertain 
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6.9.37. REDEFINES 


[ 


REDEFINES Clause Syntax } 


REDEFINES identifier-1 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 


LINKAGE 


The REDEFINES clause causes the data item in who’s definition the REDEFINES clause is 
specified (hereafter referred to as the redefines object) to occupy the same physical storage 
space as identifier-1 (hereafter referred to as the redefines subject). 


1. The following rules must all be followed in order to use REDEFINES: 


A. 
B. 


C. 


The level number of both the subject and object data items must be the same. 


The level numbers of both the subject and object data items cannot be 66, 78 or 
88. 


If N represents the level number of the object, then no other data items with level 
number N may be defined between the subject and object data items unless they 
too are REDEFINES of the subject. 

If N represents the level number of the object, then no other data items with a 
level number numerically less than N may be defined between the subject and 
object data items. 

The total allocated size of the subject data item must be the same as the total 
allocated size of the object data item. 

No OCCURS (see [OCCURS], page 190) clause may be part of the definition of either 
the subject or object data items. Either or both, however, may be group items 
that contain data items with OCCURS clauses. 

No VALUE (see [VALUE], page 244) clause may be defined on the object data item, 
and no data items subordinate to the object data item may have VALUE clauses, 
with the exception of level-88 condition names. 
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6.9.38. RENAMES 


f RENAMES Clause Syntax 


RENAMES identifier-1 [ THRU|THROUGH identifier-2 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE 


The RENAMES clause regroups previously defined items by specifying alternative, possibly 
overlapping, groupings of elementary data items. 
1. The reserved words THRU and THROUGH are interchangeable. 
2. You must use the level number 66 for data description entries that contain the RENAMES 
clause. 


3. The identifier-1 and identifier-2 data items, along with all data items defined between 
those two data items in the program source, must all be contained within the same 
01-level record description. 


4. See [66-Level Data Items], page 150, for additional information on the RENAMES clause. 
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6.9.39. REQUIRED 


REQUIRED Attribute Syntax 


REQUIRED 


This syntax is valid in the following sections: SCREEN 


This clause forces the user to enter data into the field it is specified on (or into all 
subordinate input-capable fields if REQUIRED is specified on a group item). 

1. The EMPTY-CHECK (see [EMPTY-CHECK], page 169) and REQUIRED clauses are inter- 
changeable, and may not be used together in the same data item description. 

2. In order to take effect, the user must first move the cursor into the field having this 
clause in its definition. 

3. The ACCEPT data-item statement (see [ACCEPT data-item], page 272) will ignore the 
Enter key and any other cursor-moving keystrokes that would cause the cursor to move 
to another screen item unless data has been entered into the field. Function keys will 
still be allowed to terminate the ACCEPT. 

4. In order to be functional, this attribute must be supported by the underlying “curses” 
package your GnuCOBOL implementation was built with. As of this time, the 
“PDCurses” package (used for native Windows or MinGW builds) does not support 
REQUIRED. 
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6.9.40. REVERSE-VIDEO 


( REVERSE-VIDEO Attribute Syntax 


REVERSE-VIDEO 


This syntax is valid in the following sections: SCREEN 

The REVERSE-VIDEO attribute swaps the specified or implied FOREGROUND-COLOR (see 
[FOREGROUND-COLOR], page 173) and BACKGROUND-COLOR (see [BACKGROUND- 
COLOR], page 158) attributes for the field whose definition contains this clause (or all 
subordinate fields if used on a group item). 

See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.41. SAME AS 


[ 


SAME-AS Clause Syntax 


SAME AS data-name-1 


The syntax is valid in the following sections: WORKING-STORAGE 


The SAME AS causes a data item to inherit the same definition of another data item. 


Data-name-1 is a data Item defined elsewhere in the same program. 


2. Data-name-1 shall not be subscripted. 
3. A data description entry that specifies the SAME AS clause shall not be immediately 


10. 


11. 
12. 


followed by a subordinate data description entry or level 88 entry. 


Neither the description of data-name-1 nor the description of any data items subor- 
dinate to the subject of the entry shall directly or indirectly contain a SAME AS 
clause that references the subject of the entry or any group item to which this entry is 
subordinate. 


The description of data-name-1, including its subordinate data items, shall not contain 
a TYPE clause that references the record to which this entry is subordinate. 


The description of data-name-1 shall not contain an OCCURS clause. However, items 
subordinate to data-name-1 may contain OCCURS clauses. 


Data-name-1 shall reference an elementary item or a level 1 group item described in 
the file, working-storage, local-storage, or linkage section. 


If the subject of the entry is a level 77 item, data-name-1 shall reference an elementary 
item. 


A group item to which the subject of the entry is subordinate shall not contain a 
GROUP-USAGE, SIGN, or USAGE clause. 


The effect of the SAME AS clause is as though the data description identified by data- 
name-1 had been coded in place of the SAME AS clause, excluding the level number, 
name, and the EXTERNAL, GLOBAL, REDEFINES clauses specified for data-name- 
1; level numbers of subordinate items may be adjusted as described in general rule 
2 


If data-name-1 describes a group item: 


the subject of the entry is a group whose subordinate elements have the same names, 
descriptions, and hierarchy as the subordinate elements of data-name-1, the level num- 
bers of items subordinate to that group are adjusted, if necessary, to preserve the 
hierarchy of data-name-1, level numbers in the resulting hierarchy may exceed 49. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. prog. 
DATA DIVISION. 
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15 January 2023 


WORKING-STORAGE SECTION. 
01 MESSAGE-TEXT-2 EXTERNAL. 
02 MAIN-FILE-NAME PIC X(50). 
02 FILLER REDEFINES MAIN-FILE-NAME. 
05 FILLER PIC 9999. 
02 MAIN-FILE-NAME-2. 
05 FILLER PIC 9999. 
05 DETAIL-NO PIC 9999. 
02 FILLER SAME AS MAIN-FILE-NAME. 
77 OQUTPUT-NAME SAME AS DETAIL-NO GLOBAL. 
01 Z-MESSAGE-T2 SAME AS MAIN-FILE-NAME-2. 
01 Z-MESSAGE-TS3. 
49 MT3 SAME AS MESSAGE-TEXT-2. 
49 MT3-REN REDEFINES MT3 SAME AS MESSAGE-TEXT-2. 


PROCEDURE DIVISION. 
DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2 
DISPLAY DETAIL-NO OF Z-MESSAGE-T2 
DISPLAY MAIN-FILE-NAME OF MT3 
DISPLAY OUTPUT-NAME 
GOBACK. 
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6.9.41B. SCROLL DOWN 


( SCROLL-DOWN Attribute Syntax 


SCROLL DOWN 


This syntax is valid in the following sections: SCREEN 


This clause will cause downward scrolling. 
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6.9.41C. SCROLL UP 


( SCROLL-UP Attribute Syntax } 


SCROLL UP 


This syntax is valid in the following sections: SCREEN 
This clause will cause upward scrolling. MORE HERE ?? 
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6.9.42. SECURE 


( SECURE Attribute Syntax 


SECURE 


This syntax is valid in the following sections: SCREEN 
This clause will cause all data entered into the field to appear on the screen as asterisks. 


1. The NO-ECHO (see [NO-ECHO], page 188) and SECURE clauses are interchangeable, and 
may not be used together in the same data item description. 


2. This clause may only be used on a field allowing data entry (a field containing either 
the USING (see [USING], page 243) or TO (see [TO], page 221) clause). 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.43. SIGN IS 


( SIGN-IS Clause Syntax 


SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 
This clause, allowable only for USAGE DISPLAY numeric data items, specifies how an ‘S’ 
symbol will be interpreted in a data item’s picture clause. 
1. The reserved words CHARACTER and IS are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 
2. Without the SEPARATE CHARACTER option, the sign of the data item’s value will be 
encoded by transforming the last (see TRAILING) or first (see LEADING) digit as 


follows: 

First /Last Digit Value For Positive Value for Negative 
0 0 p 
1 1 q 
2 2 if 
3 3 s 
4 4 t 
5 5 u 
6 6 v 
7 7 Ww 
8 8 x 
9 9 y 


3. If the SEPARATE CHARACTER clause is used, then an actual ‘+’ or ‘-’ character will be 
inserted into the field’s value as the first (LEADING) or last (TRAILING) character. Note 
that having this character embedded within the data item’s storage does not prevent 
the data item from being used as a source field in arithmetic operations. 

4. When SEPARATE CHARACTER is specified, the ‘S’ symbol in the data item’s PICTURE 
must be counted when determining the data item’s size. 

5. Neither the presence of an encoded digit (see above) nor an actual ‘+’ or ‘-’ character 
embedded within the data item’s storage prevents the data item from being used as a 
source field in arithmetic operations. 
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6.9.43B. SIZE 


( SIZE Clause Syntax 
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6.9.44. SOURCE 


( SOURCE Clause Syntax 


SOURCE IS literal-1 | identifier-1 [ ROUNDED ] 


This syntax is valid in the following sections: REPORT 


This clause logically attaches a report section data item to another data item defined 
elsewhere in the data division. 


1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. When the report group containing this clause is presented, the value of the specified 
numeric literal or identifier will be automatically moved to the report data item prior 
to presentation. 


3. The specified identifier may be defined anywhere in the data division, but if it is defined 
in the report section it may only be PAGE-COUNTER, LINE-COUNTER or a SUM (see [SUM], 
page 516) counter. 


4. The PICTURE (see [PICTURE], page 194) of the report data item must be such that it 
would be legal to MOVE (see [MOVE], page 352) the specified literal or identifier to a 
data item with that PICTURE. 


5. The ROUNDED option comes into play should the number of digits to the right of an 
actual or assumed decimal point be different between the specified literal or identifier 
value (the “source value”) and the PICTURE specified for the field in whose definition 
the SOURCE clause appears (the “target field”). Without ROUNDED, excess digits in the 
source value will simply be truncated to fit the target field. With ROUNDED, the source 
value will be arithmetically rounded to fit the target field. See [ROUNDED], page 261, 
for information on the NEAREST-AWAY-FROM-ZERO rounding rule, which is the one that 
will apply. 
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6.9.45. SUM OF 


( SUM-OF Clause Syntax 
SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] 
ass { literal-2 } Aaa e Ray } 
{ UPON identifier-9 } 


This syntax is valid in the following sections: REPORT 


The SUM clause establishes a summation counter whose value will be arithmetically cal- 
culated whenever the field is presented. 


1. The reserved words OF and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. The SUM clause may only appear in a CONTROL FOOTING report group. 


3. If the data item in which the SUM clause appears has been assigned its own identifier 
name, and that name is not FILLER, then that data item is referred to as a sum counter. 


4. All identifier-7 data items must be non-edited numeric in nature. 
5. If any identifier-7 data item is defined in the report section, it must be a sum counter. 
6. Any identifier-7 data items that are sum counters must either be defined in the same 


report group as the data item in which this SUM clause appears or they must be defined 
in a report data item that exists at a lower level in this report’s control hierarchy. See 
[Control Hierarchy], page 605, for additional information. 

7. The PICTURE of the report data item in who’s description this SUM clause appears in 
must be such that it would be legal to MOVE (see [MOVE], page 352) the specified 
identifier-7 or literal-2 value to a data item with that PICTURE. 

8. The following points apply to the UPON option: 


A. The data item identifier-9 must be the name of a detail group specified in the same 
report as the control footing group in which this SUM clause appears. 


B. The presence of an UPON clause limits the SUM clause to adding the specified numeric 
literal or identifier value into the sum counter only when a GENERATE identifier- 
9 statement is executed. 


C. If there is no UPON clause specified, the value of identifier-7 or literal-2 will be 
added into the sum counter whenever a GENERATE (see [GENERATE], page 332) 
of any detail report group in the report is executed. 


D. If there is only a single detail group in the report’s definition, the UPON clause is 
meaningless. 


9. The following points apply to the RESET option: 


A. If the RESET option is coded, FINAL or identifier-8 (whichever is coded on the 
RESET) must be one of the report’s control breaks specified on the CONTROLS clause. 
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B. If there is no RESET option coded, the sum counter will be reset back to zero after 
each time the control footing containing the SUM clause is presented. This is the 
typical behaviour that would be expected. 


C. If, however, you want to reset the SUM counter only when the control footing for 
a control break higher in the control hierarchy is presented, specify that higher 
control break on the RESET option. 
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6.9.46. SYNCRONIZED 


SYNCRONIZED Syntax 


SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] 


The LEFT and RIGHT (SYNCRONIZED) clauses are syntactically recognized but are other- 
wise non-functional. 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE 


This optional clause optimizes the storage of binary numeric items to store them in such 
a manner as to make it as fast as possible for the CPU to fetch them. 


1. The reserved words SYNCRONIZED and SYNCHRONISED are interchangeable, and may be 
abbreviated as SYNC. 


2. If the SYNCRONIZED clause is coded on anything but a numeric data item with a 
USAGE (see [USAGE], page 232) that specifies storage of data in a binary form, the 
SYNCRONIZED clause will be ignored. 

3. Synchronization is performed (by the compiler) as follows: 


A. Ifthe binary item occupies one byte of storage, no synchronization is performed. 


B. If the binary item occupies two bytes of storage, the binary item is allocated at 
the next half-word boundary. 


C. If the binary item occupies four bytes of storage, the binary item is allocated at 
the next word boundary. 


D. If the binary item occupies eight bytes of storage, the binary item is allocated at 
the next word boundary. 


The following illustrates the allocation of a group of data items both without and with 
the SYNCRONIZED option. The grey blocks represent the unused bytes that are allocated in 
the Group-Item-2 structure because of the SYNC clauses. 


Chapter 6 - DATA DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 219 


@1 Group-Item-1. @1 Group-Item-2. 
eS A PIC X(1). es A PIC X(1). 
@5 USAGE BINARY-SHORT. @5 B SYNC USAGE BINARY-SHORT. 
@5 PIC X(2). e5C PIC X(2). 
@5 USAGE BINARY-LONG. e5 D SYNC USAGE BINARY-LONG. 
@5 PIC X(3). @®SE PIC X(3). 
e5 USAGE BINARY-DOUBLE. @5 F SYNC USAGE BINARY-DOUBLE. 


% % % % ’ ”% 
Word Word Word Word Word Word Word Word Word Word Word Word Word 


Group-ttem-a {A] B | c [oo foe for 
Group-ttem-2 [all 6 | c [mm oo | c«§ rT 


Double Double Double Double 
Word Word Word Word 


15 January 2023 Chapter 6 - DATA DIVISION 


220 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


6.9.46B. TIME OUT 


( TIME-OUT Clause Syntax 


TIME OUT 


This syntax is valid in the following sections: SCREEN 


This clause will force a specific time for the data tp be entered. 
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6.9.47. TO 


( TO Clause Syntax ] 


TO identifier-5 


This syntax is valid in the following sections: SCREEN 
This clause logically attaches a screen section data item to another data item defined 
elsewhere in the data division. 
1. The TO clause is used to define a data-entry field with no initial value; when a value is 
entered, it will be saved to the specified identifier. 
2. The FROM (see [FROM], page 174), TO, USING (see [USING], page 243) and VALUE (see 
[VALUE], page 244) clauses are mutually-exclusive in any screen section data item’s 
definition. 
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6.9.48. TYPE 


( TYPE Clause Syntax 


Format 1: All Sections other than REPORT 


[ TYPE TO type-name-1 ] 


Format 2: REPORT SECTION Only 
[ TYPE IS { RH|{REPORT HEADING} rd 
oie th fe vere Se bang a F 
{ PH|{PAGE HEADING} } 
een ee rere bg 
{ CH| {CONTROL HEADING} FINAL|identifier-2 } 
He oe Sept eene. GIR Eytan ie 
{ DE|DETAIL F 
aaa } 
{ CF|{CONTROL FOOTING} FINAL|identifier-2 } 
A CO Veg, ig 
{ PF|{PAGE FOOTING} ay 
Met Srred Seg go ct ay } 
a i. 


The syntax is valid in all other sections than: REPORT 
As format 1 


1. The TYPE clause indicates that the data description of the subject of the entry is 
specified by a user-defined data type. 


2. The user defined data type is defined using the TYPEDEF clause, which is described 
in TYPEDEF clause TYPEDEF (see [TYPEDEF], page 227). 


3. The following general rules apply: If type-name-1 (defined using the TYPEDEF clause) 
describes a group item, then the subject of the TYPE clause is a group item whose 
subordinate elements have the same names, descriptions, and hierarchies as the subor- 
dinate elements of type-name-1. 


4. Since the subject of the TYPE clause may have a level number as high as 49 and type- 
name-1 may be a group item with 49 levels, the number of levels of this hierarchy may 
exceed 49. In fact, since descriptions of type names may reference other type names, 
there is no limit to the number of levels in this hierarchy. 


5. If a VALUE clause is specified in the data description of the subject of the TYPE 
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13. 


14. 


15. 


16. 


clause, any VALUE clause specified in the description of type-name-1 is ignored for 
this entry. 


The scoping rules for type names are similar to the scoping rules for data names. 


Reference modification is not allowed for an elementary item that is the subject of a 
TYPE clause. 


The description of type-name-1, including its subordinate data items, cannot contain a 
TYPE clause that references the record to which the subject of the TYPE clause (that 
references type-name-1), is subordinate. 


For example, A is a group item defined using the TYPEDEF clause. B is also a group 
item defined using the TYPEDEF clause, but which also includes a subordinate item of 
TYPE A. This being the case, the type definition for A cannot include items of TYPE 
B. 


The subject of a TYPE clause cannot be renamed in whole, or in part and cannot be 
redefined explicitly or implicitly. 


. If the subject of a TYPE clause is subordinate to a group item, the data description 


of the group item cannot contain the USAGE clause. 


The TYPE clause cannot occur in a data description entry with the BLANK WHEN 
ZERO, FORMAT, JUSTIFIED, PICTURE, REDEFINES, RENAMES, SIGN, SYN- 
CHRONIZED, or USAGE clause. 

The TYPE clause can be specified in a data description entry with the EXTERNAL, 
GLOBAL, OCCURS, TYPEDEF, and VALUE clauses. 

The essential characteristics of a type, which is identified by its type-name, are the 
relative positions and lengths of the elementary items defined in the type declaration, 
and the BLANK WHEN ZERO, JUSTIFIED, PICTURE, SIGN, SYNCHRONIZED, 
and USAGE clauses specified for each of these elementary items. 

The TYPE clause shall not be specified in the same data description entry with any 
clauses except BASED, CLASS, CONSTANT RECORD, DEFAULT, DESTINATION, 
entry-name, EXTERNAL, GLOBAL, INVALID, level-number, OCCURS, PRESENT 
WHEN, PROPERTY, TYPEDEF, VALIDATE-STATUS, VALUE, and VARYING. 


Figure 1. Example Showing How TYPEDEF and TYPE Clauses Can Be Used 


IDENTIFICATION DIVISION. 


PROGRAM-ID. prog. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 MAIN-FILE-NAME-T PIC X(50) IS TYPEDEF. 

01 DETAIL-NO-T PIC 9999 IS TYPEDEF. 
01 MAIN-FILE-NAME-2T IS TYPEDEF. 


05 FILLER PIC 9999. 
05 DETAIL-NO TYPE TO DETAIL-NO-T. 


O01 MESSAGE-TEXT-2T IS TYPEDEF. 
02 MAIN-FILE-NAME TYPE MAIN-FILE-NAME-T. 
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02 FILLER REDEFINES MAIN-FILE-NAME. 

05 FILLER PIC 9999. 
02 MAIN-FILE-NAME-2 TYPE MAIN-FILE-NAME-2T. 
02 FILLER TYPE MAIN-FILE-NAME-T. 


O01 MESSAGE-TEXT-2 EXTERNAL TYPE MESSAGE-TEXT-2T. 
77 OQUTPUT-NAME TYPE TO DETAIL-NO-T GLOBAL. 
01 Z-MESSAGE-T2 TYPE MAIN-FILE-NAME-2T. 
01 Z-MESSAGE-TS3. 
49 MT3 TYPE MESSAGE-TEXT-2T. 
49 MT3-REN REDEFINES MT3 TYPE MESSAGE-TEXT-2T. 


PROCEDURE DIVISION. 
DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2 
DISPLAY DETAIL-NO OF Z-MESSAGE-T2 
DISPLAY MAIN-FILE-NAME OF MT3 
DISPLAY OUTPUT-NAME 
GOBACK. 


17. Figure 2. Example Showing How TYPEDEF and TYPE Clauses Can Be Used 


DATA DIVISION. 
FILE SECTION. 


FD PRI-FILE. 
01 PRT-REC. 
05 PRT-RECORD PIC X(132). 
01 INVE-TYP-T IS TYPEDEF PIC S9(3) VALUE 0. 
88 INVE-TYP-BOOK VALUE 4, 5. 
88 INVE-TYP-BOOK-001 VALUE 4. 
88 INVE-TYP-BOOK-002 VALUE 


5 
88 INVE-TYP-CLOTHES VALUE 1 
88 INVE-TYP-CLOTHES-SWEATERS VALUE 1. 
88 INVE-TYP-CLOTHES-SOCKS VALUE 2 
88 INVE-TYP-CLOTHES-PANTS VALUE 3 


FD DATA-IN. 

01 DATA-IN-REC. 
05 INVE-TYP TYPE INVE-TYP-T. 
05 FILLER PIC X(80). 


WORKING-STORAGE SECTION. 
01 ARTI-PRICE-T TYPEDEF PIC S9(4)V9(2) value 0. 
01 ARTI-COLOR-T TYPEDEF PIC S9(2) VALUE 1. 

88 ARTI-COLOR-BLUE VALUE 1. 

88 ARTI-COLOR-RED VALUE 2. 
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O1 
01 


01 


O1 
01 


01 


01 
01 
O1 


01 


01 
O1 


01 
O1 
01 


01 
O1 


01 
O1 


15 January 2023 


88 ARTI-COLOR-GREEN VALUE 3. 


ARTI-SIZE-T TYPEDEF PIC S9(2) VALUE 10. 
ARTI-COUNTER-T TYPEDEF PIC S9(6) VALUE 0. 


ARTI-B-T TYPEDEF . 

05 ARTI-B-VALUE PIC s9(2). 
88 ARTI-B-BLUE VALUE 1. 
88 ARTI-B-RED VALUE 2. 
88 ARTI-B-GREEN VALUE 3. 


TEST-ARTI TYPE ARTI-B-T. 
WORK-INVE-TYP TYPE INVE-TYP-T. 
CLOTHING-ARTI IS TYPEDEF. 

05 CLOTHING-TYP TYPE INVE-TYP-T. 
05 PRICE TYPE ARTI-PRICE-T. 
05 COLOR TYPE ARTI-COLOR-T. 


05 CLOTHING-SIZE TYPE ARTI-SIZE-T. 
05 FILLER PIC X(70). 


SWEATERS TYPE CLOTHING-ARTI. 

SOCKS TYPE CLOTHING-ARTI. 

PANTS TYPE CLOTHING-ARTI. 
BOOK-ARTI IS TYPEDEF. 

05 BOOK-TYP TYPE INVE-TYP-T. 
05 PRICE TYPE ARTI-PRICE-T. 
05 FILLER PIC X(20). 

05 BOOK-TITLE PIC X(40). 

05 FILLER PIC X(14). 
BOOK-001 TYPE BOOK-ARTI. 
BOOK-002 TYPE BOOK-ARTI. 
SWEATERS-COUNT TYPE ARTI-COUNTER-T. 


SOCKS-COUNT TYPE ARTI-COUNTER-T. 
PANTS-COUNT TYPE ARTI-COUNTER-T. 


BOOK-001-COUNT TYPE ARTI-COUNTER-T. 
BOOK-002-COUNT TYPE ARTI-COUNTER-T. 


CLOTHES-COUNT TYPE ARTI-COUNTER-T. 
BOOK-COUNT TYPE ARTI-COUNTER-T. 


225 
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This syntax is valid in the following sections: REPORT 
As Format 2 
1. This clause defines the type of report group that is being defined for a report. 


2. This clause is required on any 01-level data item definitions (other than 01-level con- 
stants) in the report section. This clause is invalid on any other report section data 
item definitions. 


3. There may be a maximum of one (1) report group per RD defined with a TYPE of REPORT 
HEADING, PAGE HEADING, PAGE FOOTING and REPORT FOOTING. 


4. There must be either a CONTROL HEADING or a CONTROL FOOTING or both specified for 
each entry specified on the CONTROLS ARE clause of the RD. 


5. The various report groups that constitute a report may be defined in any order. 


6. See [RWCS Lexicon], page 601, for a description of the seven different types of report 
groups. 


Chapter 6 - DATA DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 227 


6.9.49. TYPEDEF 


[ 


TYPEDEF Clause Syntax } 


O1 


data-name-1i IS TYPEDEF 


This syntax is valid in the following sections FILE, WORKING-STORAGE, LOCAL- 
STORAGE and LINKAGE 


1. 


The TYPEDEF clause identifies a type declaration which creates a user defined data 
type and is used to apply this user defined data type to the description of a data item. 


2. The TYPEDEF clause specifies that the data description entry is a type declaration. 


3. The TYPEDEF clause can only be specified for level 01 entries, which can also be group 


10. 


11. 


12. 


items, and for which the data-name format of the entry name clause is specified. If the 
TYPEDEF clause is specified for a data description, then that same data description 
must include a data-name, that is, it must not be specified with either an implicit or 
explicit FILLER clause. 


If a group item is specified, all subordinate items of the group become part of the type 
declaration. 


No storage is allocated for a type declaration. 


. These type definitions act like templates that can then be used to define new data items 


using the TYPE clause or that can subsequently be referenced in a USAGE clause. 


The new data item acquires all the characteristics of the user-defined data type. If 
the user defined data type is a group item, then the new data item has subordinate 
elements of the same name, description, and hierarchy as those belonging to the user 
defined data type. 


All of the other data description clauses, if they are specified, are assumed by any data 
item that is defined using the user defined data type (within the TYPE or USAGE 
clause). 


The following clauses cannot be specified along with TYPEDEF: EXTERNAL, 
GLOBAL, LIKE, OCCURS, REDEFINES. 


If the TYPEDEF clause is specified for a group item, then subordinate items can be 
specified with OCCURS or REDEFINES clauses. TYPEDEF cannot be used with com- 
plex OCCURS DEPENDING ON. This means that you cannot specify an OCCURS 
DEPENDING ON clause within a table that is part of a TYPEDEF. 


The VALUE clause cannot be specified either in the data descriptions specifying the 
TYPEDEF clause or in any subordinate item except for condition-names (88 level 
entries) within the TYPEDEF structure. 

The TYPE clause can be specified in the same data description entry as the TYPE- 
DEF clause but the description of the subject of the entry, including its subordinate 
items, shall not contain a TYPE clause that directly or indirectly references this type 
definition. 
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13. In FILE SECTION, a data description entry declared at level number 1 that includes 
a TYPEDEF clause is not a record description entry. 
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6.9.50. UNDERLINE 


( UNDERLINE Attribute Syntax 


UNDERLINE 


This syntax is valid in the following sections: SCREEN 
The UNDERLINE clause will introduce a horizontal line at the bottom edge of a screen 
field. 
1. The LEFTLINE (see [LEFTLINE], page 181), OVERLINE (see [OVERLINE], page 193) 
and UNDERLINE clauses may be used in any combination in a single field’s description. 
2. This clause is essentially non-functional when used within Windows command shell 
(cmd.exe) environments and running programs compiled using a GnuCOBOL imple- 
mentation built using “PDCurses” (such as Windows/MinGW builds). 
3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will 
depend upon the video attribute capabilities of the terminal output drivers and “curses” 
software being used. 


See [Color Palette and Video Attributes], page 23, for more information on screen colors 
and video attributes. 
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6.9.50B. UPDATE 


( UPDATE Clause Syntax } 


UPDATE 


This syntax is valid in the following sections: SCREEN 
The UPDATE clause will display the existing data before allowing user to update it. 
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6.9.50C. UPPER 


( UPPER Clause Syntax } 


This syntax is valid in the following sections: SCREEN 
The UPPER clause force the accepted data to be in Upper Case. 
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6.9.51. USAGE 


( USAGE Clause Syntax } 


USAGE IS data-item-usage 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT 
The USAGE clause defines the format that will be used to store the value of a data item. 
1. The reserved word IS is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. The following table summarizes the various USAGE specifications available in Gnu- 
COBOL. 


BINARY 
Range of Values: Defined by the quantity of ‘9’s and the presence 
or absence of an ‘S’ in the PICTURE 
Storage Format: Compatible Binary Integer 
Negative Values Allowed?: If PICTURE contains ‘S’ 
PICTURE Used?: Yes 


BINARY-C-LONG [ SIGNED ] 

3. Depending on the system hardware, the range is either 0 to 2731 or 0 to 2°63. 
BINARY-C-LONG UNSIGNED 

4. Depending on the system hardware, the range is either 0 to 2732 or 0 to 2764. This 
USAGE should only be used for direct CALLs into C and otherwise should not be used 
(and it won’t compile with any strict -std as it is a GnuCOBOL-only extension). 
BINARY-CHAR [ SIGNED ] 


Range of Values: -128 — 127 
Storage Format: Native Binary Integer 
Negative Values Allowed?: Yes 
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PICTURE Used?: 
BINARY-CHAR UNSIGNED 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
BINARY-DOUBLE [ SIGNED ] 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
BINARY-DOUBLE UNSIGNED 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
BINARY-INT 


Same as BINARY-LONG SIGNED 


BINARY-LONG [ SIGNED ] 


Range of Values: 


Storage Format: 


15 January 2023 


No 


0 — 255 
Native Binary Integer 
No 


No 


-9,223,372,036,854,775,808 
9,223,372,036,854,775,807 


Native Binary Integer 
Yes 


No 


0 — 18,446,744,073,709,551,615 
Native Binary Integer 
No 


No 


-2,147,483,648 — 2,147,483,647 


Native Binary Integer 
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Negative Values Allowed?: Yes 


PICTURE Used?: No 
BINARY-LONG UNSIGNED 


Range of Values: 0 — 4,294,967,295 


Storage Format: Native Binary Integer 


Negative Values Allowed?: No 


PICTURE Used?: No 
BINARY-LONG-LONG 


Same as BINARY-DOUBLE SIGNED 
BINARY-SHORT [ SIGNED ] 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
BINARY-SHORT UNSIGNED 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


COMPUTATIONAL 
COMP 


Same as BINARY 


COMPUTATIONAL-1 
COMP-1 
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-32,768 — 32,767 
Native Binary Integer 
Yes 


No 


0 — 65,535 
Native Binary Integer 
No 


No 
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Same as FLOAT-SHORT 


COMPUTATIONAL-2 
COMP-2 


Same as FLOAT-LONG 


COMPUTATIONAL-3 
COMP-3 


Same as PACKED-DECIMAL 
COMPUTATIONAL-4 
COMP-4 

Same as BINARY 
COMPUTATIONAL-5 
COMP-5 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
COMPUTATIONAL-6 
COMP-6 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
COMPUTATIONAL-X 
COMP-X 


Range of Values: 
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Depends on number of ‘9’s in the PICTURE and 
the binary-size setting of the configuration file 
used to compile the program 

Native Binary Integer 

If PICTURE contains ‘S’ 


Yes 


Defined by the quantity of ‘9’s and the presence 
or absence of an ‘S’ in the PICTURE 


Unsigned Packed Decimal 
No 


Yes 


If used with PIC X, allocates one byte of storage 
per ‘X’; range of values is 0 to max storable in 
that many bytes. If used with PIC 9, range of 
values depends on number of ‘9’s in PICTURE 
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Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


DISPLAY 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


FLOAT-DECIMAL-16 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


FLOAT-DECIMAL-34 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


FLOAT-LONG 


Range of Values: 
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Native unsigned (X) or signed (9) Binary 
If PICTURE 9 and contains ‘S’ 


Yes 


Depends on PICTURE — One character per X, A, 
9, period, $, Z, 0, *, S (if SEPARATE CHARACTER 
specified), +, - or B symbol in PICTURE; Add 2 
more bytes if the DB or CR editing symbol is used 
Characters 


If PICTURE contains ‘S’ 


Yes 


-9.999999999999999 * 102% 
9.999999999999999 * 10°84 


Native IEEE 754 Decimal64 Floating-point 
Yes 


No 


-9.99999... * 10°!48 — 9.99999... * 10%!44 
Native IEEE 754 Decimal128 Floating-point 
Yes 


No 


Approximately -1.797693134862316 * 10308 — 
1.797693134862316 * 1038 
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FLOAT- 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 
SHORT 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


NATIONAL 


Native IEEE 754 Binary64 Floating-point 
Yes 


No 


Approximately -3.4028235 * 10°° — 3.4028235 * 
1038 


Native IEEE 754 Binary32 
Yes 


No 


0 to maximum address possible (32 or 64 bits) 
Native Binary Integer 
No 


No 


USAGE NATIONAL, while syntactically recognized, is not supported by GnuCOBOL 
PACKED-DECIMAL 


Range of Values: 


Storage Format: 


Negative Values Allowed?: 


PICTURE Used?: 


POINTER 
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Defined by the quantity of ‘9’s and the presence 
or absence of an ‘S’ in the PICTURE 


Signed Packed Decimal 
If PICTURE contains ‘S’ 


Yes 
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Range of Values: 0 to maximum address possible (32 or 64 bits) 
Storage Format: Native Binary Integer 

Negative Values Allowed?: No 

PICTURE Used?: No 


PROCEDURE-POINTER 


Same as PROGRAM-POINTER 
PROGRAM-POINTER 


Range of Values: 0 to maximum address possible (32 or 64 bits) 
Storage Format: Native Binary Integer 
Negative Values Allowed?: No 
PICTURE Used?: No 
SIGNED-INT 


Same as BINARY-LONG SIGNED 
SIGNED-LONG 


Same as BINARY-DOUBLE SIGNED 
SIGNED-SHORT 


Same as BINARY-SHORT SIGNED 
UNSIGNED-INT 


Same as BINARY-LONG UNSIGNED 
UNSIGNED-LONG 


Same as BINARY-DOUBLE UNSIGNED 
UNSIGNED-SHORT 
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Same as BINARY-SHORT UNSIGNED 
. USAGE IS type-name-1 


239 


. This USAGE clause indicates that the data description of the subject of the entry is 
specified by a user-defined data type. The user-defined data type is defined using the 


TYPEDEF clause, which is described in TYPEDEF clause. 


Example 1: 


01 struct-1 TYPEDEF . 
05 part-1 pic x(20). 
05 part-2 pic x(10). 
Ol a. 
05 b USAGE struct-1. 
05 x USAGE USHORT. 


01 USHORT pic 9(04) comp-5 typedef. 


Which would be interpreted as if it had been coded as: 


Ol a. 
05 b. 
10 part-1 pic x(20). 
10 part-2 pic x(10). 


05 x pic 9(04) comp-5. 


Example 2: 


IDENTIFICATION DIVISION. 
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02 MAIN-FILE-NAME-2 


02 FILLER 


PROGRAM-ID. prog. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
O1 MAIN-FILE-NAME-T PIC X(50) IS TYPEDEF. 
01 DETAIL-NO-T PIC 9999 IS TYPEDEF. 
O1 MAIN-FILE-NAME-2T IS TYPEDEF. 
05 FILLER PIC 9999. 
05 DETAIL-NO USAGE DETAIL-NO-T. 
O1 MESSAGE-TEXT-2T IS TYPEDEF . 
O02 MAIN-FILE-NAME USAGE MAIN-FILE-NAME-T. 
02 FILLER REDEFINES MAIN-FILE-NAME. 
05 FILLER PIC 9999. 


USAGE MAIN-FILE-NAME-2T. 
USAGE MAIN-FILE-NAME-T. 
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01 MESSAGE-TEXT-2 EXTERNAL USAGE MESSAGE-TEXT-2T. 


77 OUTPUT-NAME USAGE DETAIL-NO-T GLOBAL. 
01 Z-MESSAGE-T2 USAGE MAIN-FILE-NAME-2T. 
01 Z-MESSAGE-T3. 

49 MT3 USAGE MESSAGE-TEXT-2T. 


49 MT3-REN REDEFINES MT3 USAGE MESSAGE-TEXT-2T. 


PROCEDURE DIVISION. 
DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2 
DISPLAY DETAIL-NO OF Z-MESSAGE-T2 
DISPLAY MAIN-FILE-NAME OF MT3 
DISPLAY OUTPUT-NAME 


GOBACK. 
Example 3: 
77 ~=INT PIC S9(09)COMP-5 IS TYPEDEF. 
O01 Z-RETURNCODE USAGE INT VALUE 0. 
O1 MESSAGE-TEXT-2 IS TYPEDEF . 
02 MAIN-FILE-NAME PIC X(50). 
02 FILLER PIC X(79). 
O01 Z-MESSAGE-T2 USAGE MESSAGE-TEXT-2. 
77 VIRMSG-TEXT PIC X(129) IS TYPEDEF. 
O1 MESSAGE-TEXT-2 IS TYPEDEF. 
02 MAIN-FILE-NAME PIC X(50). 
02 FILLER PIC-X (79) 
O1 Z-MESSAGE-TEXT USAGE VIRMSG-TEXT. 


01 Z-MESSAGE-T2 REDEFINES Z-MESSAGE-TEXT USAGE MESSAGE-TEXT-2. 
01 W102-TYPE IS TYPEDEF. 
COPY SERVERFIELDS. 
01 T-A USAGE W102-TYPE. 
01 T-N USAGE W102-TYPE. 


7. Binary data (integer or floating-point) can be stored in either a Big-Endian or Little- 
Endian form. 


Big-endian data allocation calls for the bytes that comprise a binary item to be allocated 
such that the least-significant byte is the right-most byte. For example, a four-byte 
binary item having a value of decimal 20 would be big-endian allocated as 00000014 
(shown in hexadecimal notation). 


Little-endian data allocation calls for the bytes that comprise a binary item to be 
allocated such that the least-significant byte is the left-most byte. For example, a 
four-byte binary item having a value of decimal 20 would be little-endian allocated as 
14000000 (shown in hexadecimal notation). 
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10. 


All CPUs are capable of understanding big-endian format, which makes it the most 
compatible form of binary storage across computer systems. 


Some CPUs — such as the Intel/AMD i386/x64 architecture processors used in most 
Windows PCs — prefer to process binary data stored in a little-endian format. Since 
that format is more efficient on those systems, it is referred to as the native binary 
format. 


On a system supporting only one format of binary storage (generally, that would be 
big-endian), the terms most efficient and native format are synonymous. 


Data items that have the UNSIGNED attribute explicitly coded, or DISPLAY, 
PACKED-DECIMAL, COMP-5, COMP-X items that do not have an ‘S’ symbol in their 
picture clause cannot preserve negative values that may be stored into them. Storing 
a negative value into such a field will actually result in the sign being stripped, 
essentially saving the absolute value in the data item. 


Packed-decimal (i.e. USAGE PACKED-DECIMAL, USAGE COMP-3 or USAGE COMP-6) data is 
stored as a series of bytes such that each byte contains two 4-bit fields, referred to 
as nibbles (since they comprise half a “byte”, they’re just “nibbles” — don’t groan, I 
don’t just make this stuff up!). Each nibble represents a ‘9’ in the PICTURE and each 
holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, ... ,9 = 
1001). 


The last byte of a PACKED-DECIMAL or COMP-3 data item will always have its left 
nibble corresponding to the last ‘9’ in the PICTURE and its right nibble reserved as a 
sign indicator. This sign indicator is always present regardless of whether or not the 
PICTURE included an ‘S’ symbol. 


The first byte of the data item will contain an unused left nibble if the PICTURE had 
an even number of ‘9’ symbols in it. 


The sign indicator will have a value of a hexadecimal A through F. Traditional packed 
decimal encoding rules call for hexadecimal values of F, A, C or E (“FACE”) in the 
sign nibble to indicate a positive value and B or D to represent a negative value (hex- 
adecimal digits 0-9 are undefined). Testing with a Windows MinGW/GnuCOBOL 
implementation shows that — in fact — hex digit D represents a negative number and 
any other hexadecimal digit denotes a positive number. Therefore, a PIC S9(3) COMP-3 
packed-decimal field with a value of -15 would be stored internally as a hexadecimal 
015D in GnuCOBOL. 


If you attempt to store a negative number into a packed decimal field that has no ‘S’ 
in its PICTURE, the absolute value of the negative number will actually be stored. 


USAGE COMP-6 does not allow for negative values, therefore no sign nibble will be al- 
located. A USAGE COMP-6 data item containing an odd number of ‘9’ symbols in its 
PICTURE will leave its leftmost nibble unused. 


The USAGE specifications FLOAT-DECIMAL-16 and FLOAT-DECIMAL-34 will encode data 
using IEEE 754 Decimal64 and Decimal128 format, respectively. The former allows 
for up to 16 digits of exact precision while the latter offers 34. The phrase “exact 
precision” is used because the traditional binary renderings of decimal real numbers 
in a floating-point format (FLOAT-LONG and FLOAT-SHORT, for example) only yield an 
approximation of the actual value because many decimal fractions cannot be precisely 
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rendered in binary. The Decimal64 and Decimal128 renderings, however, render deci- 
mal real numbers in encoded decimal form in much the same way that PACKED-DECIMAL 
renders a decimal integer in digit-by-digit decimal form. The exact manner in which 
this rendering is performed is complex (Wikipedia has an excellent article on the subject 
— just search for Decimal64). 

GnuCOBOL stores FLOAT-DECIMAL-16 and FLOAT-DECIMAL-34 data items using either 
Big-Endian or Little-Endian form, whichever is native to the system. 

The USAGE specifications FLOAT-LONG and FLOAT-SHORT use the IEEE 754 Binary64 
and Binary32 formats, respectively. These are binary encodings of real decimal num- 
bers, and as such cannot represent every possible value between the minimum and 
maximum values in the range for those usages. Wikipedia has an excellent article on 
the Binary64 and Binary32 encoding schemes — just search on Binary32 or Binary64. 
GnuCOBOL stores FLOAT-LONG and FLOAT-SHORT data items using either Big-Endian 
or Little-Endian form, whichever is native to the system. 

A USAGE clause specified at the group item level will apply that USAGE to all subordinate 
data items, except those that themselves have a USAGE clause. 


The only USAGE that is allowed in the report section is USAGE DISPLAY. 
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6.9.52. USING 


( USING Clause Syntax 


USING identifier-1 


This syntax is valid in the following sections: SCREEN 
This clause logically attaches a screen section data item to another data item defined 
elsewhere in the data division. 
1. When the screen item whose definition this clause is part of is displayed, the value 
currently in identifier-1 will be automatically moved into the screen item first. 


2. When the screen item whose definition this clause is part of (or its parent) is accepted, 
the current contents of the screen item will be saved back to identifier-1 at the conclu- 
sion of the ACCEPT. 

3. The FROM (see [FROM], page 174), TO (see [TO], page 221), USING and VALUE (see 
[VALUE], page 244) clauses are mutually-exclusive in any screen section data item’s 
definition. 
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6.9.53. VALUE 


VALUE (Condition Names) Clause Syntax 


{ VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}... 


srosedey ; Leeda ete 


[ 


This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, 
LINKAGE, REPORT, SCREEN 


The VALUE clause is used to define condition names or to assign values (at compilation 


time) to data items. 


1. 


The reserved words ARE and IS are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


This clause cannot be specified on the same data item as a FROM (see [FROM], page 174), 
TO (see [TO], page 221) or USING (see [USING], page 243) clause. 


The following points apply to using the VALUE clause in the definition of a condition 


name: 

A. The clauses VALUE IS and VALUES ARE are interchangeable. 

B. The reserved words THRU and THROUGH are interchangeable. 

C. See [88-Level Data Items], page 153, for a discussion of how this format of VALUE 

is used to create condition names. 

D. See [Condition Names], page 45, for a discussion of how condition names are used. 
The following points apply to using the VALUE clause in the definition of any other data 
item: 

A. In this context, VALUE specifies an initial compilation-time value that will be as- 


signed to the storage occupied by the data item in the program object code gen- 
erated by the compiler. 

The VALUE clause is ignored on EXTERNAL (see [EXTERNAL], page 171) data items 
or on any data items defines as subordinate to an EXTERNAL data item. 

This format of the VALUE clause may not be used anywhere in the description of an 
01 item (or any of its subordinate items) serving as an FD or SD record description. 
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D. Ifthe optional ALL clause is used, it may only be used with an alphanumeric literal 
value; the value will be repeated as needed to completely fill the data item. Here 
are some examples with and without ALL (the symbol b denotes a space): 


PIC X(5) VALUE ‘A’ *> Abbbb 
PIC X(5) VALUE ALL ‘A’ *> AAAAA 
PIC 9(3) VALUE 1 *> O01 


PIC 9(3) VALUE ALL ‘1’ *> 4111 


E. When used in the definition of a screen data item: 


d. 


A figurative constant may not be supplied as literal-1. 

Any FROM (see [FROM], page 174), TO (see [TO], page 221) or USING (see 
[USING], page 243) clause in the same data item’s definition will be ignored. 
If there is no picture clause specified, the size of the screen data item will be 
the length of the literal-1 value. 

If there is no picture clause and the ALL option is specified, the ALL option 
will be ignored. 


F. Giving a table an initial, compile-time value is one of the trickier aspects of COBOL 
data definition. There are basically three standard techniques and a fourth that 
people familiar with other COBOL implementations but new to GnuCOBOL may 
find interesting. So, here are the three standard approaches: 


a. 


Don’t bother worrying about it at compile-time. Use the INITIALIZE (see 
[INITIALIZE], page 339) to initialize all data item occurrences in a table (at 
run-time) to their data-type-specific default values (numerics: 0, alphabetic 
and alphanumerics: spaces). 

Initialize small tables at compile time by including a VALUE clause on the 
group item that serves as a parent to the table, as follows: 


05 SHIRT-SIZES VALUE "S 14M 15L 16XL17". 
10 SHIRT-SIZE-TBL OCCURS 4 TIMES. 
15 SST-SIZE PIC X(2). 
15 SST-NECK PIC 9(2). 


Initialize tables of almost any size at compilation time by utilizing the 
REDEFINES (see [REDEFINES], page 204) clause: 


05 SHIRT-SIZE-VALUES. 


10 PIC X(4) VALUE "S 14". 
10 PIC X(4) VALUE "M 15". 
10 PIC X(4) VALUE "L 16". 
10 PIC X(4) VALUE "XL1i7". 
05 SHIRT-SIZES REDEFINES SHIRT-SIZE-VALUES. 
10 SHIRT-SIZE-TBL OCCURS 4 TIMES. 
15 SST-SIZE PIC X(2). 
15 SST-NECK PIC 9(2). 


Admittedly, this table is much more verbose than the one shown with a group 
VALUE. What is good about this initialization technique, however, is that you 
can have as many FILLER and VALUE items as you need for a larger table, and 
those values can be as long as necessary! 
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G. Many COBOL compilers do not allow the use of VALUE and OCCURS (see [OCCURS], 


page 190) on the same data item; additionally, they don’t allow a VALUE clause on 
a data item subordinate to an OCCURS. GnuCOBOL, however, has neither of these 
restrictions! 


Observe the following example, which illustrates a fourth manner in which tables 
may be initialized in GnuCOBOL: 


O05 X OCCURS 6 TIMES. 
10 A PIC X(1) VALUE ’?’. 
10 B PIC X(1) VALUE ’%’. 
10 N PIC 9(2) VALUE 10. 


In this example, all six ‘A’ items will be initialized to ‘?’, all six ‘B’ items will be 


initialized to ‘%’ and all six ‘N’ items will be initialized to 10. It’s not clear exactly 
how many times this sort of initialization will be useful, but it’s there if you need 
it. 


5. The FROM (see [FROM], page 174), TO (see [TO], page 221), USING (see [USING], 


page 243) and VALUE clauses are mutually-exclusive in any screen section data item’s 
definition. 


End of Chapter 6 — DATA DIVISION 
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7. PROCEDURE DIVISION 


[ PROCEDURE DIVISION Syntax 


PROCEDURE DIVISION [ { USING Subprogram-Argument ... +] 
a ae ras Tia te Meg } 


— 
is} 
3) 
Q 
7 
> 
be] 
> 
‘=| 
H 
< 
3) 
n 
ws 
g 
g 
g 
g 
g 
g 
a 
a 
g 


Vga § 


Event-Handler-Routine... . ] 


rt 


END DECLARATIVES. ] 


General-Program-Logic 


| ae 


Nested-Subprogram... |] 


eb 


END PROGRAM|FUNCTION name-1 ] 


The PROCEDURE DIVISION of any GnuCOBOL program marks the point where all executable 
code is written. 
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7.1. PROCEDURE DIVISION USING 


[ 


PROCEDURE DIVISION Subprogram-Argument Syntax 


[ BY { REFERENCE [ OPTIONAL ] } ] identifier-1 
Aven cutapes | Vee } 
{ VALUE [ [ UNSIGNED ] SIZE IS { AUTO } ] } 
Spee + Pee eee ee pane 5 peated } 
{ DEFAULT } 
a a aes } 
{ integer-1 } 


The USING clause defines the arguments that will be passed to a GnuCOBOL program 
which is serving as a subprogram. 


1. 


The reserved words BY and IS are optional and may be omitted. The presence or 
absence of these words have no effect upon the program. 


The USING clause should only be used on the procedure division header of subprograms 
(subroutines or user-defined functions). 


The calling program will pass zero or more data items, known as arguments, to this 
subprogram — there must be exactly as many identifier-1 data items specified on the 
USING clause as the maximum number of arguments the subprogram will ever be passed. 
If a subprogram does not expect any arguments, it should not have a USING clause 
specified on its procedure division header. 

The order in which arguments are defined on the USING clause must correspond to 
the order in which those arguments will be passed to the subprogram by the calling 
program. 

The identifiers specified on the USING clause must be defined in the linkage section of 
the subprogram. No storage is actually allocated for those identifiers in the subprogram 
as the actual storage for them will exist in the calling program. 

A GnuCOBOL subprogram expects that all arguments to it will be one of two things: 


e The memory address of the actual data item (allocated in the calling program) 
that is being passed to the subprogram. 

e A numeric, full-word, binary value (i.e. USAGE BINARY-LONG (see [USAGE], 
page 232)) which is the actual argument being passed to the subprogram. 


In the case of the former, the USING clause on the procedure division header should 
describe the argument via the BY REFERENCE clause — in the latter case, a BY VALUE 
specification should be coded. This allows the code generated by the compiler to 
properly reference the subprogram arguments at run-time. 


BY REFERENCE is the assumed default for the first USING argument should no BY clause 
be specified for it. Subsequent arguments will assume the BY specification of the argu- 
ment prior to them should they lack a BY clause of their own. 
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9. Changes made by a subprogram to the value of an argument specified on the USING 
clause will “be visible” to the calling program only if BY REFERENCE was explicitly 
specified or implicitly assumed for the argument on the subprogram’s procedure division 
header and the argument was passed to the subprogram BY REFERENCE by the calling 
program. See [Subprogram Arguments], page 682, for additional information on the 
mechanics of how arguments are passed to subprograms. 


10. The optional SIZE clause allows you to specify the number of bytes a BY VALUE argument 
will occupy, with SIZE DEFAULT specifying 4 bytes (this is the default if no SIZE clause 
is used), SIZE AUTO specifying the size of the argument in the calling program and SIZE 
integer-1 specifying a specific byte count. 

11. The optional UNSIGNED keyword, legal only if SIZE AUTO or SIZE integer-1 are coded, 
will add the unsigned attribute to the argument’s specification in the C-language 
function header code generated for the subprogram. While not of any benefit when 
the calling program is a GnuCOBOL program, this can improve compatibility with a 
C-language calling program. 


12. The OPTIONAL keyword, legal only on BY REFERENCE arguments, allows calling pro- 
grams to code OMITTED for that corresponding argument when they call this subpro- 
gram. See [CALL], page 293. for additional information on this feature. 
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7.2. PROCEDURE DIVISION CHAINING 


[ 


PROCEDURE DIVISION Main-Program-Argument Syntax 


[ BY REFERENCE ] [ OPTIONAL ] identifier-1 


The CHAINING term provides one mechanism a programmer may use to retrieve command- 
line arguments passed to a program at execution time. 
1. PROCEDURE DIVISION CHAINING may only be coded in a main program (that is, the 
first program executed when a compiled GnuCOBOL compilation unit is executed). It 
cannot be used in any form of subprogram. 


2. The CHAINING clause defines arguments that will be passed to a main program from 
the operating system. The argument identifiers specified on the CHAINING clause will 
be populated by character strings comprised of the parameters specified to the program 
on the command line that executed it, as follows: 


A. 


When a GnuCOBOL program is executed from a command-line, the complete 
command line text will be broken into a series of tokens, where each token is 
identified as being a word separated from the others in the command text by 
at least one space. For example, if the command line was /usr/local/myprog 
THIS IS A TEST, there will be five tokens identified by the operating system — 
‘/usr/local/myprog’, ‘THIS’, ‘IS’, ‘A’ and ‘TEST’. 


. Multiple space-delimited tokens may be treated as a single token by enclosing them 


in quotes. For example, there are only three tokens generated from the command 
line C:\Pgms\myprog.exe ‘THIS IS A’ TEST — ‘C:\Pgms\myprog.exe’, ‘THIS IS 
A’ and ‘TEST’. When quote characters are used to create multi-word tokens, the 
quote characters themselves are stripped from the token’s value. 


. Once tokens have been identified, the first one (the command) will be discarded; 


the rest will be stored into the CHAINING arguments when the program begins 
execution, with the 2nd token going to the 1° argument, the 3rd token going to 
the 2nd argument and so forth. 


. If there are more tokens than there are arguments, the excess tokens will be dis- 


carded. 


If there are fewer tokens than there are arguments, the excess arguments will 
be initialized as if the INITIALIZE identifier-1 (see [INITIALIZE], page 339) 
statement were executed. 


. All identifiers specified on the CHAINING clause should be defined as PIC X, PIC 


A, group items (which are treated implicitly as PIC X) or as PIC 9 USAGE DISPLAY. 
The use of USAGE BINARY (or the like) data items as CHAINING arguments is not 
recommended as all command-line tokens will be retained in their original character 
form as they are moved into the argument data items. 


If an argument identifier is smaller in storage size than the token value to be stored 
in it, the right-most excess characters of the token value will be truncated as the 
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value is moved in. Any JUSTIFIED RIGHT clause on such an argument identifier 
will be ignored. 


H. If an argument is larger in storage size than the token value to be stored in it, the 
token value will be moved into the argument identifier in a left-justified manner. 
unmodified-modified byte positions in the identifier will be space filled, unless the 
argument identifier is defined as PIC 9 USAGE DISPLAY, in which case unmodified 
bytes will be filled with ‘0’ characters from the systems native character set. 
This behaviour when the argument is defined as PIC 9 may be unacceptable, as an 
argument defined as PIC 9(3) but passed in a value of ‘1’ from the command line 
will receive a value of ‘100’, not ‘001’. Consider defining “numeric” command line 
arguments as PIC X and then using the NUMVAL intrinsic function (see [NUMVAL], 
page 492) function to determine the proper numeric value. 
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7.3. PROCEDURE DIVISION RETURNING 


f PROCEDURE DIVISION RETURNING Syntax 


RETURNING identifier-1 


The RETURNING clause on the PROCEDURE DIVISION header documents that the 
subprogram in which the clause appears will be returning a numeric value back to the 
program that called it. 


1. The RETURNING clause is optional within a subroutine, as not all subroutines return a 
value to their caller. 


2. The RETURNING clause is mandatory within a user-defined function, as all such must 
return a numeric result. 


3. The identifier-1 data item should be defined as a USAGE BINARY-LONG data item. 


4. Main programs that wish to “pass back” a return code value to the operating system 
when they exit do not use RETURNING - they do so simply by MOVEing a value to the 
RETURN-CODE special register. 


5. This is not the only mechanism that a subprogram may use to pass a value back to its 
caller. Other possibilities are: 


A. The subprogram may modify any argument that is specified as BY REFERENCE on 
its PROCEDURE DIVISION header. Whether the calling program can actually “see” 
any modifications depends upon how the calling program passed the argument to 
the subprogram. See [CALL], page 293, for more information. 


B. A data item with the GLOBAL (see [GLOBAL], page 176) attribute specified in its 
description in the calling program is automatically visible to and updatable by a 
subprogram nested with the calling program. See [Independent vs Contained vs 
Nested Subprograms], page 675, for more information on subprogram nesting. 

C. A data item defined with the EXTERNAL (see [EXTERNAL], page 171) attribute 
in a subprogram and the calling program (same name in both programs) is auto- 
matically visible to and updatable by both programs, even if those programs are 
compiled separately from one another. 
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7.4. PROCEDURE DIVISION Sections and Paragraphs 


The procedure division is the only one of the COBOL divisions that allows you to create 
your own sections and paragraphs. These are collectively referred to as Procedures, and 
the names you create for those sections and paragraphs are called Procedure Names. 


Procedure names are optional in the procedure division and — when used — are named 
entirely according to the needs and whims of the programmer. 


Procedure names may be up to thirty one (31) characters long and may consist of letters, 
numbers, dashes and underscores. A procedure name may neither begin nor end with a 
dash (‘-’) or underscore (‘_’) character. This means that Main, 0100-Read-Transaction 
and 17 are all perfectly valid procedure names. 


There are three circumstances under which the use of certain GnuCOBOL statements 
or options will require the specification of procedures. These situations are: 


1. When DECLARATIVES (see [DECLARATIVES], page 254) are specified. 
2. When the ENTRY statement (see [ENTRY], page 318) is being used. 


3. When any procedure division statement that references procedures is used. These 
statements are: 


e ALTER procedure-name 

e GO TO procedure-name 

e MERGE ... OUTPUT PROCEDURE procedure-name 
e PERFORM procedure-name 


e SORT ... INPUT PROCEDURE procedure-name and/or SORT ... INPUT PROCEDURE 
procedure-name 
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7.5. DECLARATIVES 


[ DECLARATIVES Syntax 


section-name-1i SECTION. 


USE { [ GLOBAL ] AFTER STANDARD { EXCEPTION } PROCEDURE ON { INPUT } 
ONE. oP pee , eae aaiaas } a a es } 
{ { ERROR } { OUTPUT } 
cr eats } 
{ { I-0 } 
{ FOR DEBUGGING ON { procedure-name-1 } {7 } 
Ay RR { ALL PROCEDURES } { EXTEND } 
{ Oa ia ees } ae } 
{ { REFERENCES OF identifier-1 } { file-name-1 } 
{ 
{ [ GLOBAL ] BEFORE REPORTING identifier-2 
{ wnnnnnwn NAW N RR NAW WWW 
{ 
{ 


The AFTER EXCEPTION CONDITION and AFTER EC clauses are syntactically recognized but 
are otherwise non-functional. 


SHY YY Ye 


The DECLARATIVES area of the procedure division allows the programmer to define a 
series of “trap” procedures (referred to as declarative procedures) capable of intercepting 
certain events that may occur at program execution time. The syntax diagram above shows 
the format of a single such procedure. 


1. The reserved words AFTER, FOR, ON, PROCEDURE and STANDARD are optional and may be 
omitted. The presence or absence of these words has no effect upon the program. 


2. EC and EXCEPTION CONDITION are interchangeable. 


3. The declaratives area may contain any number of declarative procedures, but no two 
declarative procedures should be coded to trap the same event. 


4. The following points apply to the USE BEFORE REPORTING clause: 
A. identifier-2 must be a report group. 


B. At run-time, the declaratives procedure will be executed prior to the processing 
of the specified report group’s presentation; within the procedure you may take 
either of the following actions: 


e You may adjust the value(s) of any items referenced in SUM (see [SUM], 
page 516) or SOURCE (see [SOURCE], page 215) clauses in the report group. 


e You may execute the SUPPRESS (see [SUPPRESS], page 409) statement to 
squelch the presentation of the specified report group altogether. Note that 
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you will be suppressing this one specific instance of that group’s presentation 
and not all of them. 


5. The following points apply to the USE FOR DEBUGGING clause: 


A. 


This clause allows you to define a declarative procedure that will be invoked 
whenever... 


e ...identifier-1 is referenced on any statement. 
e ...procedure-name-1 is executed. 


e ...any procedure is executed (ALL PROCEDURES). 


. A USE FOR DEBUGGING declarative procedure will be ignored at compilation time 


unless WITH DEBUGGING MODE is specified in the SOURCE-COMPUTER (see [SOURCE- 
COMPUTER], page 89) paragraph. Neither the compiler’s -fdebugging-line 
switch nor -debug switch will activate this feature. 


Any USE FOR DEBUGGING declarative procedures will be ignored at execution time 
unless the COB_SET_DEBUG run-time environment variable (see [Run Time Envi- 
ronment Variables], page 654) has been set to a value of ‘Y’, ‘y’ or ‘1’. 


. The typical use of a USE FOR DEBUGGING declarative procedure is to display the 


DEBUG-ITEM special register, which will be implicitly and automatically created in 
your program for you if WITH DEBUGGING MODE is active. 


The structure of DEBUG-ITEM will be as follows: 
O01 DEBUG-ITEM. 


05 DEBUG-LINE PIC X(6). 
05 FILLER PIC X(1) VALUE SPACE. 
05 DEBUG-NAME PIC X(31). 
05 FILLER PIC X(1) VALUE SPACE. 
05 DEBUG-SUB-1 PIC S9(4) SIGN LEADING SEPARATE. 
05 FILLER PIC X(1) VALUE SPACE. 
05 DEBUG-SUB-2 PIC S9(4) SIGN LEADING SEPARATE. 
05 FILLER PIC X(1) VALUE SPACE. 
05 DEBUG-SUB-3 PIC S9(4) SIGN LEADING SEPARATE. 
05 FILLER PIC X(1) VALUE SPACE. 
05 DEBUG-CONTENTS PIC X(31). 
where... 
DEBUG-LINE 
. is the program line number of the statement that triggered the 
declaratives procedure. 
DEBUG-NAME 
. is the procedure name or identifier name that triggered the declar- 
atives procedure. 
DEBUG-SUB-1 


. is the first subscript value (if any) for the reference of the identifier 
that triggered the declaratives procedure. 
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DEBUG-SUB-2 
. is the second subscript value (if any) for the reference of the iden- 
tifier that triggered the declaratives procedure. 


DEBUG-SUB-3 
. is the third subscript value (if any) for the reference of the identifier 
that triggered the declaratives procedure. 


DEBUG-CONTENTS 
. is a (brief) statement of the manner in which the procedure that 
triggered the declaratives procedure was executed or the first 31 char- 
acters of the value of the identifier whose reference triggered the declar- 
atives procedure (the value after the statement was executed). 

6. The USE AFTER STANDARD ERROR PROCEDURE clause defines a declarative procedure in- 
voked any time a failure is encountered with the specified I/O type (or against the 
specified file(s)). 

7. The GLOBAL (see [GLOBAL], page 176) option, if used, allows a declarative procedure 
to be used across the program containing the USE statement and any subprograms 
nested within that program. 


8. Declarative procedures may not reference any other procedures defined outside the 
scope of DECLARATIVES. 


7.6. Common Clauses on Executable Statements 


7.6.1. AT END + NOT AT END 


AT END Syntax } 


[ AT END imperative-statement-1 ] 


[ NOT AT END imperative-statement-2 ] 


AT END clauses may be specified on READ (see [READ], page 366), RETURN (see [RETURN], 
page 373), SEARCH (see [SEARCH], page 377) and SEARCH ALL (see [SEARCH ALL], 
page 379) statements. 


1. The following points pertain to the use of these clauses on READ (see [READ], page 366) 
and RETURN (see [RETURN], page 373) statements: 


A. The AT END clause will — if present — cause imperative-statement-1 (see 
[Imperative Statement], page 718) to be executed if the statement fails due to 
a file status of 10 (end-of-file). See [File Status Codes], page 107, for a list of 
possible File Status codes. 


An AT END clause will not detect other non-zero file-status values. 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 257 


Use a DECLARATIVES (see [DECLARATIVES], page 254) routine or an explicitly- 
declared file status field tested after the READ or RETURN to detect error conditions 
other than end-of-file. 


B. A NOT AT END clause will cause imperative-statement-2 to be executed if the READ 
or RETURN attempt is successful. 


2. The following points pertain to the use of these clauses on SEARCH (see [SEARCH], 
page 377) and SEARCH ALL (see [SEARCH ALL], page 379) statements: 


A. An AT END clause detects and handles the case where either form of table search 
has failed to locate an entry that satisfies the search conditions being used. 


B. The NOT AT END clause is not allowed on either form of table search. 
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7.6.2. CORRESPONDING 


Three GnuCOBOL statements — ADD (see [ADD CORRESPONDING], page 288), MOVE 
(see [MOVE CORRESPONDING], page 353) and SUBTRACT (see [SUBTRACT CORRE- 
SPONDING], page 407) support the use of a CORRESPONDING option: 

ADD CORRESPONDING group-item-1 TO group-item-2 

MOVE CORRESPONDING group-item-1 TO group-item-2 

SUBTRACT CORRESPONDING group-item-1 FROM group-item-2 

This option allows one or more data items within one group item (group-item-1 — the 
first named on the statement) to be paired with correspondingly-named (hence the name) in 
a second group item (group-item-2 — the second named on the statement). The contents of 
group-item-1 will remain unaffected by the statement while one or more data items within 
group-item-2 will be changed. 

In order for data-item-1, defined subordinate to group item group-item-1 to be a corre- 
sponding match to data-item-2 which is subordinate to group-item-2, each of the following 
must be true: 

1. Both data-item-1 and data-item-2 must have the same name, and that name may not 
explicitly or implicitly be FILLER. 
2. Both data-item-1 and data-item-2... 
A. ...must exist at the same relative structural “depth” of definition within group- 
item-1 and group-item-2, respectively 
B. ...and all “parent” data items defined within each group item must have identical 
(but non-FILLER) names. 
3. When used with a MOVE verb... 
A. ...one of data-item-1 or data-item-2 (but not both) is allowed to be a group item 
B. ...and it must be valid to move data-item-1 TO data-item-2. 


4. When used with ADD or SUBTRACT verbs, both data-item-1 and data-item-2 must be 
numeric, elementary, unedited items. 

5. Neither data-item-1 nor data-item-2 may be a REDEFINES (see [REDEFINES], 
page 204) or RENAMES (see [RENAMES], page 205) of another data item. 


6. Neither data-item-1 nor data-item-2 may have an OCCURS (see [OCCURS], page 190) 
clause, although either may contain subordinate data items that do have an OCCURS 
clause (assuming rule 3a applies) 


Observe the definitions of data items ‘Q’ and ‘Y’... 


O1 Q. O1 Y. 
03 X. 02 A PIC X(1). 
05 A PIC 9(1). 02 Gil. 
05 Gi. 03 G2. 
10 G2. 04B- PIC X(1). 
15 B- PIC X(1). 02 C PIC X(1). 
05 C. 02 G3. 
10 FILLER PIC X(1). 03 G5. 
05 G3. 04D PIC X(1). 
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10 G4. 03 G6 PIC X(1). 
15D PIC X(1). O2E PIC 9(1). 
O5 E PIG KCL). 02 F PIC X(1). 
05 F REDEFINES V1 02G PIC X(4). 
PIC X(1). 02 H OCCURS 4 TIMES 
05 G. PIC X(1). 
10 G6 OCCURS 4 TIMES 661 RENAMES E. 
PIC X(1). 02 J. 
05 H PIC X(4). 03 K. 
05 I PIC 9(1). 04 L. 
05 J. O05 M. 
10 K. 


15 M PIC X(1). 

The following are the valid CORRESPONDING matches, assuming the statement MOVE 
CORRESPONDING X TO Y is being executed (there are no valid corresponding matches for ADD 
CORRESPONDING or SUBTRACT CORRESPONDING because every potential match up violates rule 
#4): 

A, B, C,G 

The following are the CORRESPONDING match ups that passed rule #1 (but failed on 

another rule), and the reasons why they failed. 


Data Failure Reason 

Item 

D Fails due to rule #2b 
E Fails due to rule #3b 
F Fails due to rule #5 
G1 Fails due to rule #3a 
G2 Fails due to rule #3a 
G3 Fails due to rule #3a 
G4 Fails due to rule #1 
G5 Fails due to rule #1 
G6 Fails due to rule #6 


H Fails due to rule #6 
I Fails due to rule #5 
J Fails due to rule #3a 
K Fails due to rule #3a 
L Fails due to rule #1 
M Fails due to rule #2a 


6.3. INVALID KEY + NOT INVALID KEY 


7. 
( INVALID KEY Syntax 


[ INVALID KEY imperative-statement-1 ] 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


260 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


[ NOT INVALID KEY imperative-statement-2 ] 


INVALID KEY clauses may be specified on DELETE (see [DELETE], page 304), READ (see 
[Random READ], page 368), REWRITE (see [REWRITE], page 374), START (see [START], 
page 397) and WRITE (see [WRITE], page 417) statements. 


Specification of an INVALID KEY clause will allow your program to trap an I/O failure 
condition (with an I/O error code in the file’s FILE-STATUS (see [SELECT], page 104) field) 
that has occurred due to a record-not-found condition and handle it gracefully by executing 
imperative-statement-1 (see [Imperative Statement], page 718). 


An optional NOT INVALID KEY clause will cause imperative-statement-2 to be executed 
if the statement’s execution was successful. 


7.6.4. ON EXCEPTION + NOT ON EXCEPTION 


ON EXCEPTION Syntax 


[ ON EXCEPTION imperative-statement-1 ] 


EXCEPTION clauses may be specified on ACCEPT (see [ACCEPT], page 268), CALL (see 
[CALL], page 293) and DISPLAY (see [DISPLAY], page 305) statements. 


Specification of an exception clause will allow your program to trap a failure condi- 
tion that has occurred and handle it gracefully by executing imperative-statement-1 (see 
(Imperative Statement], page 718). If such a condition occurs at runtime without having one 
of these clauses specified, an error message will be generated (by the GnuCOBOL runtime 
library) to the SYSERR device (pipe 2). The program may also be terminated, depending 
upon the type and severity of the error. 


An optional NOT ON EXCEPTION clause will cause imperative-statement-2 to be executed 
if the statement’s execution was successful. 


7.6.5. ON OVERFLOW + NOT ON OVERFLOW 


i ON OVERFLOW Syntax 


[ ON OVERFLOW imperative-statement-1 ] 
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OVERFLOW clauses may be specified on CALL (see [CALL], page 293), STRING (see [STRING], 
page 401) and UNSTRING (see [UNSTRING], page 413) statements. 


An ON OVERFLOW clause will allow your program to trap a failure condition that has 
occurred and handle it gracefully by executing imperative-statement-1 (see [Imperative 
Statement], page 718). If such a condition occurs at runtime without having one of these 
clauses specified, an error message will be generated (by the GnuCOBOL runtime library) 
to the SYSERR device (pipe 2). The program may also be terminated, depending upon the 
type and severity of the error. 


An optional NOT ON OVERFLOW clause will cause imperative-statement-2 to be executed 
if the statement’s execution was successful. 


7.6.6. ON SIZE ERROR + NOT ON SIZE ERROR 


[ ON SIZE ERROR Syntax 


[ ON SIZE ERROR imperative-statement-1 ] 


SIZE ERROR clauses may be included on ADD (see [ADD], page 284), COMPUTE (see 
[COMPUTE], page 301), DIVIDE (see [DIVIDE], page 312), MULTIPLY (see [MULTIPLY], 
page 354) and SUBTRACT (see [SUBTRACT], page 403) statements. 


Including an ON SIZE ERROR clause on an arithmetic statement will allow your program to 
trap a failure of an arithmetic statement (either generating a result too large for the receiving 
field, or attempting to divide by zero) and handle it gracefully by executing imperative- 
statement-1 (see [Imperative Statement], page 718). Field size overflow conditions occur 
silently, usually without any runtime messages being generated, even though such events 
rarely lend themselves to generating correct results. Division by zero errors, when no 
ON SIZE ERROR clause exists, will produce an error message (by the GnuCOBOL runtime 
library) to the SYSERR device (pipe 2) and will also abort the program. 


An optional NOT ON SIZE ERROR clause will cause imperative-statement-2 to be executed 
if the arithmetic statement’s execution was successful. 


7.6.7. ROUNDED 


[ ROUNDED Syntax 


ROUNDED [ MODE IS { AWAY-FROM-ZERO J 
err li ee gen ieee as 
{ NEAREST-AWAY-FROM-ZERO } 
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We YY YY 


GnuCOBOL provides for control over the final rounding process applied to the receiving 
fields on all arithmetic verbs. Each of the arithmetic statements (ADD (see [ADD], page 284), 
COMPUTE (see [COMPUTE], page 301), DIVIDE (see [DIVIDE], page 312), MULTIPLY (see 
[MULTIPLY], page 354) and SUBTRACT (see [SUBTRACT], page 403)) statements allow an 
optional ROUNDED clause to be applied to each receiving data item. 
The following rules apply to the rounding behaviour induced by this clause. 
1. Rounding only applies when the result being saved to a receiving field with a ROUNDED 
clause is a non-integer value. 
2. Absence of a ROUNDED clause is the same as specifying ROUNDED MODE IS TRUNCATION. 
3. Use of a ROUNDED clause without a MODE specification is the same as specifying ROUNDED 
MODE IS NEAREST-AWAY-FROM-ZERO. 


The behaviour of the eight different rounding modes is defined in the following table. 
Note that a‘...’ indicates the last digit repeats. The examples assume an integer receiving 
field. 


AWAY-FROM-ZERO 
Rounding is to the nearest value of larger magnitude. 


-3.510 = -4 +3.510 = +4 
-3.500 = -4 +3.500 => +4 
-3.499... => -4 +3.499... => +4 
-2.500 = -3 +2.500 = +3 
-2.499... > -3 +2.499... > +3 


NEAREST-AWAY-FROM-ZERO 
Rounding is to the nearest value (larger or smaller). If two values are equally 
near, the value with the larger absolute value is selected. 


-3.510 = -4 +3.510 => +4 
-3.500 = -4 +3.500 = +4 
-3.499... > -3 +3.499... => +3 
-2.500 = -3 +2.500 = +3 
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-2.499... => -2 +2.499... => +2 


NEAREST-EVEN 
Rounding is to the nearest value (larger or smaller). If two values are equally 
near, the value whose rightmost digit is even is selected. This mode is sometimes 
called “Banker’s rounding”. 


-3.510 = -4 +3.510 = +4 
-3.500 = -4 +3.500 = +4 
-3.499... > -3 +3.499... > +3 
-2.500 = -2 +2.500 = +2 
-2.499... => -2 +2.499... => +2 


NEAREST-TOWARD-ZERO 
Rounding is to the nearest value (larger or smaller). If two values are equally 
near, the value with the smaller absolute value is selected. 


-3.510 = -4 +3.510 => +4 
-3.500 = -3 +3.500 = +3 
-3.499... > -3 +3.499... > +3 
-2.500 = -2 +2.500 = +2 
-2.499... => -2 +2.499... => +2 


PROHIBITED 
No rounding is performed. If the value cannot be represented exactly in the 
desired format, the EC-SIZE-TRUNCATION condition (exception code 1005) is set 
(and may be retrieved via the ACCEPT (see [ACCEPT FROM Runtime-Info], 
page 281) statement) and the results of the operation are undefined. 


-3.510 = Undefined 
-3.500 = Undefined 


-3.499... = Undefined 


-2.500 = Undefined 


-2.499... = Undefined 


TOWARD-GREATER 


+3.510 = Undefined 
+3.500 = Undefined 
+3.499... = Undefined 
+2.500 = Undefined 
+2.499... = Undefined 


Rounding is toward the nearest value whose algebraic value is larger. 


-3.510 = -3 
-3.500 = -3 
-3.499... > -3 
-2.500 = -2 
-2.499... => -2 


TOWARD-LESSER 


+3.510 = +4 
+3.500 => +4 
+3.499... => +4 
+2.500 > +3 
+2.499... > +3 


Rounding is toward the nearest value whose algebraic value is smaller. 


-3.510 = -4 
-3.500 = -4 
-3.499... => -4 
-2.500 = -3 
-2.499... > -3 
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+3.510 => +3 
+3.500 => +3 
+3.499... > +3 
+2.500 => +2 
+2.499... > +2 
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TRUNCATION 
Rounding is to the nearest value whose magnitude is smaller. 
-3.510 => -3 +3.510 => +3 
-3.500 => -3 +3.500 => +3 
-3.499... > -3 +3.499... > +3 
-2.500 = -2 +2.500 => +2 
-2.499... => -2 +2.499... > +2 
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7.7. Special Registers 


GnuCOBOL, like other COBOL dialects, includes a number of data items that are auto- 
matically available to a programmer without the need to actually define them in the data 
division. COBOL refers to such items as registers or special registers. The special registers 
available to a GnuCOBOL program are as follows: 


COB-CRT-STATUS 
PIC 9(4) — This is the default data item allocated for use by the ACCEPT 
data-item statement (see [ACCEPT data-item], page 272), if no CRT STATUS 
(see [SPECIAL-NAMES], page 92) clause was specified.. 


DEBUG-ITEM 
Group Item — A group item in which debugging information generated by a 
USE FOR DEBUGGING section in the declaratives area of the procedure division 
will place information documenting why the USE FOR DEBUGGING procedure was 
invoked. Consult the DECLARATIVES (see [DECLARATIVES], page 254) docu- 
mentation for information on the structure of this register. 


LINAGE-COUNTER 
BINARY-LONG SIGNED — An occurrence of this register exists for each selected 
file having a LINAGE (see [File/Sort-Description], page 124) clause. If there are 
multiple files whose file descriptions have LINAGE clauses, any explicit references 
to this register will require qualification (using OF file-name). The value of 
this register will be the current logical line number within the page body. The 
value of this register cannot be modified. 


LINE-COUNTER 
BINARY-LONG SIGNED — An occurrence of this register exists for each report 
defined in the program (via an RD (see [REPORT SECTION], page 135)). If 
there are multiple reports, any explicit references to this register not made in 
the report section will require qualification (OF report-name). The value of 
this register will be the current logical line number on the current page. The 
value of this register cannot be modified. 


NUMBER-OF-CALL-PARAMETERS 
BINARY-LONG SIGNED — This register contains the number of arguments passed 
to a subroutine — the same value that would be returned by the C$NARG built- 
in system subroutine (see [CSNARG], page 548). Its value will be zero when 
referenced in a main program. This register, when referenced from within a 
user-defined function, returns a value of one (‘1’) if the function has any number 
of arguments and a zero if it has no arguments. 


PAGE-COUNTER 
BINARY-LONG SIGNED — An occurrence of this register exists for each report 
having an RD (see [REPORT SECTION], page 135). If there are multiple such 
reports, any explicit references to this register not made in the report section 
will require qualification ( OF report-name). The value of this register will be 
the current report page number. The value of this register cannot be modified. 
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RETURN-CODE 

BINARY-LONG SIGNED — This register provides a numeric data item into which 
a subroutine may MOVE (see [MOVE], page 352) a value (which will then be 
available to the calling program) prior to transferring control back to the pro- 
gram that called it, or into which a main program may MOVE a value before 
returning control to the operating system. Many built-in subroutines will re- 
turn a value using this register. These values are — by convention — used to 
signify success (usually with a value of 0) or failure (usually with a non-zero 
value) of the process the program was attempting to perform. This register may 
also be modified by a subprogram as a result of that subprogram’s use of the 
RETURNING (see [PROCEDURE DIVISION RETURNING], page 252) clause. 


SORT-RETURN 
BINARY-LONG SIGNED — This register is used to report the success/fail status 
of a RELEASE (see [RELEASE], page 371) or RETURN (see [RETURN], page 373) 
statement. A value of 0 is reported on success. A value of 16 denotes failure. 
An AT END (see [AT END + NOT AT END], page 256) condition on a RETURN 
is not considered a failure. 


WHEN-COMPILED 
PIC X(16) — This register contains the date and time the program was com- 
piled in the format ‘mm/dd/yyhh.mm.ss’. Note that only a two-digit year is 
provided. 
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LENGTH OF Syntax ] 


LENGTH OF numeric-literal-1 | identifier-1 


Alphanumeric literals and identifiers may optionally be prefixed with the LENGTH OF 
clause. The compile-time value generated by this clause will be the number of bytes in the 
alphanumeric literal or the defined size (in bytes) of the identifier. 


1. The reserved word OF is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. Here is an example. The following two 
GnuCOBOL statements both display the same result (27): 


O01 Demo-Identifier PIC X(27). 


DISPLAY LENGTH OF "This is a LENGTH OF Example" 
DISPLAY LENGTH OF Demo-Identifier 


2. The LENGTH OF clause on a literal or identifier reference may generally be used anywhere 
a numeric literal might be specified, with the following exceptions: 


e As part of the FROM clause of a WRITE (see [WRITE], page 417) or RELEASE state- 
ment (see [RELEASE], page 371). 


e As part of the TIMES clause of a PERFORM statement (see [PERFORM], page 360). 
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7.8. GnuCOBOL Statements 
7.8.1. ACCEPT 


7.8.1.1. ACCEPT FROM CONSOLE 


ACCEPT FROM CONSOLE Syntax 


ACCEPT { identifier-1 } [ FROM mnemonic-name-1 ] 


{ OMITTED } 


This format of the ACCEPT statement is used to read a value from the console window or 
the standard input device and store it into a data item (identifier-1). 


1. If no FROM clause is specified, FROM CONSOLE is assumed. 
2. The specified mnemonic-name-1 must either be one of the built-in device names 


CONSOLE, STDIN, SYSIN or SYSIPT, or a user-defined (see [SPECIAL-NAMES], 
page 92) mnemonic name attached to one of those four device names. 

3. Input will be read either from the console window (CONSOLE) or from the system- 
standard input (pipe 0 = STDIN, SYSIN or SYSIPT) and will be saved in identifier-1. 

4. If identifier-1 is a numeric data item, the character value read from the console or 
standard-input device will be parsed according to the rules for input to the NUMVAL 
intrinsic function (see [NUMVAL], page 492), except that none of the trailing sign 
formats are honoured. 
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7.8.1.2. ACCEPT FROM COMMAND-LINE 


ACCEPT FROM COMMAND-LINE Syntax 


ACCEPT identifier-1 


FROM { COMMAND-LINE } 
See Wits qeereenge ree } 
{ ARGUMENT-NUMBER } 
esi aa Aa } 
{ ARGUMENT-VALUE } 
fe BPE PO RE } 


mM 


NOT ON EXCEPTION imperative-statement-2 ] 


[ END-ACCEPT ] 


This format of the ACCEPT statement is used to retrieve information from the program’s 
command line. 


1. The reserved word ON is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. When you accept from the COMMAND-LINE option, you will retrieve the entire set of 
arguments entered on the command line that executed the program, exactly as they 
were specified. Parsing that returned data into its meaningful information will be your 
responsibility. 

3. Using COMMAND-LINE or ARGUMENT-VALUE in a *nix based platform and that includes 
Linux, OSX, BSD and under windows running msys or MinGW etc, the shell process 
will expand any arguments that have a ‘*’ in the list — such as ‘a*’, ‘abc*.*’, etc. — 
and create a list of all files that match the pattern. To avoid this if not wanted, put 
all such argument within quotes, e.g., progundertest "a*" bcd "ef*" "*hg" and 
the text within quotes will be passed verbatim to the program (as in the example 
progundertest). 


4. By accepting from ARGUMENT-NUMBER, you will be asking the GnuCOBOL run-time 


system to parse the arguments from the command line and return the number of 
arguments found. Parsing will be conducted according to the following rules: 


A. Arguments will be separated by treating spaces and/or tab characters as the delim- 
iters between arguments. The number of such delimiters separating two non-blank 
argument values is irrelevant. 


B. Strings enclosed in double-quote characters (‘"’) will be treated as a single argu- 
ment, regardless of how many spaces or tab characters (if any) might be embedded 
within the quotation characters. 
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C. On Windows systems, single-quote, or apostrophe, characters (‘’’) will be treated 
just like any other data character and will not delineate argument strings. 

5. By accepting from ARGUMENT-VALUE, you will be asking the GnuCOBOL run-time sys- 
tem to parse the arguments from the command line and return the “current” argument. 
You specify which argument number is “current” via the ARGUMENT-NUMBER option on 
the DISPLAY statement (see [DISPLAY UPON COMMAND-LINE]}, page 307). Parsing 
of arguments will be conducted according to the rules set forth above. 

6. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect 
and react to the failure or success, respectively, of an attempt to retrieve an 
ARGUMENT-VALUE. See [ON EXCEPTION + NOT ON EXCEPTION], page 260, for 
additional information. 
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7.8.1.3. ACCEPT FROM ENVIRONMENT 


ACCEPT FROM ENVIRONMENT Syntax } 


ACCEPT identifier-1 
FROM { ENVIRONMENT-VALUE 
~nwnwe { www nwnwnwnwnwnwnwnwnwnwnwnwwwe 
{ ENVIRONMENT { literal-1 


} 
} 
aes 

eh SEs et { identifier-1 } } 
1] 


rm 
io) 
a 
ea 
es 
Q 
ez 
U 
cal 
H 
fo) 
2 
H- 
B 
ue) 
oO 
4 
ry) 
ct 
H- 
<q 
(0) 
| 
n 
Cu 
ry) 
ct 
0) 
B 
0) 
bp 
i 


mom 


NOT ON EXCEPTION imperative-statement-2 ] 


[ END-ACCEPT ] 


This format of the ACCEPT statement is used to retrieve environment variable values. 


1. The reserved word ON is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. By accepting from ENVIRONMENT-VALUE, you will be asking the GnuCOBOL run-time 
system to retrieve the value of the environment variable whose name is currently in 
the ENVIRONMENT-NAME register. A value may be placed into the ENVIRONMENT-NAME 
register using the ENVIRONMENT-NAME option of the DISPLAY statement (see [DISPLAY 
UPON ENVIRONMENT-NAME), page 308). 

3. A simpler approach to retrieving an environment variables value is to use the 
ENVIRONMENT option, where you specify the environment variable whose value is to be 
retrieved right on the ACCEPT statement itself. 

4. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to an attempt to retrieve the value of a non-existent environment variable or the 


successful retrieval of an environment variable’s value, respectively. See [ON EXCEP- 
TION + NOT ON EXCEPTION], page 260, for additional information. 
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7.8.1.4. ACCEPT data-item 


( ACCEPT data-item Syntax 


ACCEPT { identifier-1 } 


{ OMITTED } 


[{ FROM EXCEPTION-STATUS }] 


[ AT { | LINE NUMBER { integer-1 } | $ ] 
cia el ae { identifier-2 } | } 
{ | COLUMN|COL|POSITION|POS NUMBER { integer-2 } 
Aes lt Nee re earn og ae { identifier-3 } 
< - 
{ { integer-3 } } 
{ { identifier-4 } } 
[ WITH [ Attribute-Specification ]... 
[ LOWER|UPPER ] 
[ SCROLL { UP } [ { integer-4 } LINE|LINES ] ] 
Seger 2%, ie }©=©6 { identifier-5 } 
{ DOWN } 


— 


TIMEOUT|TIME-OUT AFTER { integer-5 } ] 
ee ee teen ers { identifier-6 } 


_ 
Q 
j=) 
Sa 
< 
GI 
as] 
n 
H 
j=) 
Sa 
uw 


loon] 
SG 
‘U 
iw] 
> 
4 
ima 

wi 


[ SIZE { integer-6 | 
~~~  { identifier-7 } 
[ ON EXCEPTION imperative-statement-1 ] 


{[ NOT ON EXCEPTION imperative-statement-2 ] 


[ END-ACCEPT ] 


The FROM CRT, MODE IS BLOCK and CONVERSION clauses are syntactically recognized but 
are otherwise non-functional. 
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This format of the ACCEPT statement is used to retrieve data from a working storate 


item or a formatted console window screen. 


1. 


The reserved words AFTER, IS, NUMBER and ON are optional and may be omitted. The 
presence or absence of these words has no effect upon the program. 


2. The reserved words COLUMN, COL and POSITION are interchangeable. 
3. The reserved words TIMEOUT and TIME-OUT are interchangeable. 
4. If identifier-1 is defined in the SCREEN SECTION (see [SCREEN SECTION], page 143), 


15 


any AT, Attribute-Specification, LOWER, UPPER or SCROLL clauses will be ignored. In 

these cases, an implied DISPLAY (see [DISPLAY data-item], page 311) of identifier-1 will 

occur before input is accepted. Coding an explicit DISPLAY identifier-1 before an 

ACCEPT identifier-1 is redundant and will incur the performance penalty of painting 

the screen contents twice. 

The various AT clauses provide a means of positioning the cursor to a specific spot on 

the screen before the screen is read. One or the other (but not both) may be used, as 

follows: 

A. The LINE and COLUMN clauses provide one mechanism for specifying the line and 
column position to which the cursor will be positioned before allowing the user to 
enter data. In the absence of one or the other, a value of 1 will be assumed for 
the one that is missing. The author’s personal preference, however, is to explicitly 
code both. 

B. The literal-3 or identifier-4 value, if specified, must be a four- or six-digit value 
with the 1°* half of the number indicating the line where the cursor should be 
positioned and the second half indicating the column. You may code only one of 
each clause on any ACCEPT. 

WITH options (including the various individual Attribute-Specifications) should be 

coded only once. 

The following Attribute-Specification clauses are allowed on the ACCEPT statement; 

these are the same as those allowed for SCREEN SECTION data items. A particular 

Attribute-Specification may be used only once in any ACCEPT: 

e AUTO (see [AUTO], page 155), AUTO-SKIP (see [AUTO-SKIP], page 156), 
AUTOTERMINATE (see [AUTOTERMINATE], page 157), TAB 

e BACKGROUND-COLOR (see [BACKGROUND-COLOR], page 158) 

e BEEP (see [BEEP], page 161), BELL (see [BELL], page 162) 

e BEFORE TIME (see [BEFORE TIME], page 159) 

e BLINK (see [BLINK], page 165) 

e FOREGROUND-COLOR (see [FOREGROUND-COLOR], page 173) 

e FULL (see [FULL], page 175), LENGTH-CHECK (see [LENGTH-CHECK], page 182) 

e HIGHLIGHT (see [HIGHLIGHT], page 178) 

e LEFTLINE (see [LEFTLINE], page 181) 


e LOWER (see [LOWER], page 185) 
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10. 
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e LOWLIGHT (see [LOWLIGHT], page 186) 

e NO UPDATE (see [NO UPDATE], page 189) 

e OVERLINE (see [|OVERLINE], page 193) 

e PROMPT (see [PROMPT], page 202) 

e PROTECTED (see [PROTECTED], page 203) 

e REQUIRED (see [REQUIRED], page 206), EMPTY-CHECK (see [EMPTY-CHECK], 
page 169) 

e REVERSE-VIDEO (see [REVERSE-VIDEO], page 207) 

e SCROLL DOWN (see [SCROLL DOWN], page 210) 

e SCROLL UP (see [SCROLL UP], page 211) 

e SIZE (see [SIZE], page 214) 

e SECURE (see [SECURE], page 212), NO-ECHO (see [NO-ECHO], page 188) 

e TIME OUT (see [TIME OUT], page 220) 

e UPDATE (see [UPDATE], page 230) 

e UPPER (see [UPPER], page 231) 

e UNDERLINE (see [UNDERLINE], page 229) 


The SCROLL option will cause the entire contents of the screen to be scrolled UP or 
DOWN by the specified number of lines before any value is displayed on the screen. It is 
syntactically allowable to specify a SCROLL UP clause as well as a SCROLL DOWN clause. 
In such an instance, it is the last one specified that will be honoured. If no LINES 
specification is made, 1 LINE will be assumed. 

The TIMEOUT option will cause the ACCEPT to wait no more than the specified number 
of seconds for input. The wait count may be specified as a positive integer or a numeric 
data item with a positive value. 

The UPDATE option will enable the supplied data field to be updated having been 
displayed on screen prior to data being entered by overwriting, if needed. When this 
option is not used the input field is cleared prior to input and this is the default but can 
be changed by the use of compiler steering command -faccept-with-update that can be 
input when starting the compiler or included in the configuration file e.g., default.conf 
used when selected by default -std=default. For more information see (undefined) 
[cobe - The GnuCOBOL Compiler], page (undefined), option switches) and [Compiler 
Configuration Files], page 645. 

This format of the ACCEPT statement will be terminated by any of the following events: 
A. When the Enter key is pressed. 


B. Expiration of the TIMEOUT timer — this will be treated as if the Enter key had 
been pressed with no data being entered. 
C. When a function key (Fn) is pressed. 


D. The pressing of the PgUp or PgDn keys, if the COB_SCREEN_EXCEPTIONS run-time 
environment variable (see [Run Time Environment Variables], page 654) is set to 
any non-blank value. 
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E. 


F. 


The pressing of the Esc key if both the COB_SCREEN_ESC run-time environment 
variable as well as COB_SCREEN_EXCEPTIONS run-time environment variable are 
set to any non-blank value. 

The pressing of the Up-arrow, Down-Arrow or PrtSc (Print Screen) keys. These 
keys are not detectable on Windows systems, however. 


12. The following apply when identifier-1 is defined in the SCREEN SECTION: 


A. 


Alphanumeric data entered into identifier-1 or any screen data item subordinate 
to it must be consistent with the PICTURE (see [PICTURE], page 194) clause of 
that item. This will be enforced at runtime by the ACCEPT statement. 


. If identifier-1 or any screen data item subordinate to it are defined as numeric, 


entered data must be acceptable as NUMVAL intrinsic function (see [NUMVAL], 
page 492) input (no decimal points are allowed, however). The value stored into 
the screen data item will be as if the input were passed to that function. 


If identifier-1 or any screen data item subordinate to it are defined as numeric 
edited, entered data must be acceptable as NUMVAL-C intrinsic function (see 
[NUMVAL-C], page 493) input (again, no decimal points are allowed). The value 
stored into the screen data item will be as if the input were passed to that 
function. 


13. The following apply when identifier-1 is not defined in the SCREEN SECTION: 


A. 


Alphanumeric data entered into identifier-1 should be consistent with the PICTURE 
(see [PICTURE], page 194) clause of that item, although that will not be enforced 
by the ACCEPT statement. You may use Class Conditions (see [Class Conditions], 
page 46) after the data is accepted to enforce the data type. 


. If identifier-1 is defined as numeric, entered data must be acceptable as NUMVAL 


intrinsic function (see [NUMVAL], page 492) input (no decimal points are allowed, 
however). The value stored into identifier-1 will be as if the input were passed to 
that function. 

If identifier-1 is defined as numeric edited, entered data must be acceptable as 
NUMVAL-C intrinsic function (see [NUMVAL-C], page 493) input (again, no decimal 
points are allowed). The value stored into identifier-1 will be as if the input were 
passed to that function. 


14. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to the failure or success, respectively, of the screen I/O attempt. See [ON EX- 
CEPTION + NOT ON EXCEPTION], page 260, for additional information. 

After this format of the ACCEPT statement is executed, the program’s CRT STATUS (see 
[SPECIAL-NAMES], page 92) identifier will be populated with one of the following: 


Code 
0000 
1001-1064 
2001 

2002 

2003 
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Meaning 

ENTER key pressed 

F1i-F64, respectively, were pressed 
PgUp was pressed 

PgDn was pressed 

Up-Arrow was pressed 
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2004 
2005 
2006 
2007 
2008 
2009 
2010 
2011 
2012 
2013 
2014 
2015 
2040- 
2040 
2041 
2042 
2043 
2044 
2045 
2046 
2047 
2048 
2049 
2050 
2051 
2052 
2053 
2054 
2055 
2056- 
2057 
2058 
2059 
2060 
2061 
2062 
2063 
2064 
2065 
2066 
2067 
2068 
2069 
2070 
2071 
2072 


Down-Arrow was pressed 

Esc was pressed 

PrtSc (Print Screen) was pressed 
Tab 

Back Tab 

Key Left 

Key Right 

Insert Key on accept omitted 
Delete Key on accept omitted 
Backspace Key on accept omitted 
Home Key on accept omitted 
End Key on accept omitted 
2095 Exception keys for Mouse Handling 
Mouse Move 

Left Pressed 

Left Released 

Left Dbl Click 

Mid Pressed 

Mid Released 

Mid Dbl Click 

Right Pressed 

Right Released 

Right Dbl Click 

Shift Move 

Shift Left Pressed 

Shift Left Released 

Shift Left Dbl Click 

Shift Mid Pressed 

Shift Mid Released 

Shift Mid Dbl Click 

Shift Right Pressed 

Shift Right Released 

Shift Right Dbl Click 

Ctrl Move 

Ctrl Left Pressed 

Ctrl Left Released 

Ctrl Left Dbl Click 

Ctrl Mid Pressed 

Ctrl Mid Released 

Ctrl Mid Dbl Click 

Ctrl Right Pressed 

Ctrl Right Released 

Ctrl Right Dbl Click 

Alt Move 

Alt Left Pressed 

Alt Left Released 
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15. 


2073- Alt Left Dbl Click 
2074 Alt Mid Pressed 
2075 Alt Mid Released 
2076 Alt Mid Dbl Click 
2077 Alt Right Pressed 
2078 Alt Right Released 
2079 Alt Right Dbl Click 
2080 Wheel Up 
2081 Wheel Down 
2082 Wheel Left 
2083 Wheel Right 
2084 Shift Wheel Up 
2085 Shift Wheel Down 
2086 Shift Wheel Left 
2087 Shift Wheel Right 
2088 Ctrl Wheel Up 
2089 Ctrl Wheel Down 
2090 Ctrl Wheel Left 
2091 Ctrl Wheel Right 
2092 Alt Wheel Up 
2093 Alt Wheel Down 
2094 Alt Wheel Left 
2095 Alt Wheel Right 
Input validation 
8000 NO Field 
8001 Time Out 
Other errors 
9000 Fatal 
9001 Max Field 


The actual key pressed to generate a function key (Fn) will depend on the type of 
terminal device you’re using (PC, Macintosh, VT100, etc.) and what type of enhanced 
display driver was configured with the version of GnuCOBOL you're using. 


For example, on a GnuCOBOL build for a Windows PC using MinGW and “PD- 
Curses”, F1-F12 are the actual F-keys on the PC keyboard, F13-F24 are entered by 
shifting the F-keys, F25-F36 are entered by holding Ctrl while pressing an F-key and 
F37-F48 are entered by holding Alt while pressing an F-key. On the other hand, a 
GnuCOBOL implementation built for Windows using Cygwin and NCurses treats the 
PCs F1i-F12 keys as the actual F1-F12, while shifted F-keys will enter F11-F20. With 
Cygwin/NCurses, Ctrl- and Alt-modified F-keys aren’t recognized, nor are Shift-F11 
or Shift-F12. 


Mouse Key codes are populated only if mouse management has been enabled. To en- 
able mouse it is first necessary to set COB_LMOUSE_FLAGS (either externally via terminal 
command, or internally via SET ENVIRONMENT to the applicable ?mouse mask? (speci- 
fying which activities you wish the program to detect). Here is an example of setting 
the mask from a COBOL program: 
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18. 
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COPY screenio.cpy. 


01 mouse-flags PIC 9(4). 


COB-AUTO-MOUSE-HANDLING 
COB-ALLOW-LEFT-DOWN 
COB-ALLOW-MIDDLE-DOWN 
COB-ALLOW-RIGHT-DOWN 


COMPUTE mouse-flags 


+ + t+ 


SET ENVIRONMENT "COB_MOUSE_FLAGS" TO mouse-flags. 


Once that has been done, every (extended) ACCEPT, will return a value in 
COB_CRT_STATUS reflecting mouse activity, when such activity occurs. The 
applicable values are shown in screenio.cpy under ?Exception keys for mouse 
handling?. If you define a variable in SPECIAL NAMES as follows: 


SPECIAL-NAMES. 
CURSOR IS data-name. *> where data-name is PIC 9(4) or 9(6). 


The cursor or mouse position will be returned as well. The position is expressed as row 
and column (rrcc or rrrecc). 


Numeric keypad keys are not recognizable on Windows MinGW/PDCurses builds of 
GnuCOBOL, regardless of the number lock settings. Windows Cygwin/NCurses builds 
recognize numeric keypad inputs properly. Although not tested during the preparation 
of this documentation, I would expect native Windows builds using PDCurses to behave 
as MinGW builds do and native Unix builds using NCurses to behave as do Cygwin 
builds. 


The optional EXCEPTION-STATUS clause may be used to detect exceptions from a prior 
arithmetic verb such as COMPUTE to recover any errors produced. These are recov- 
ered using the function EXCEPTION-STATUS. 
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7.8.1.5. ACCEPT FROM DATE/TIME 


ACCEPT FROM DATE/TIME Syntax | 
ACCEPT identifier-1 FROM { DATE [ YYYYMMDD ] } 
Se mah Pe EE ees SEE © 
{ DAY [ YYYYDDD ] } 
, LS EEL } 
{ DAY-OF-WEEK r 
re gh aig } 
{ TIME } 
ee } 
{ MICROSECOND-TIME } 
Ep Perg ters eye rene } 


[ END-ACCEPT ] 


This format of the ACCEPT statement is used to retrieve the current system date, time or 
current day of the week and store it into a data item. 


1. The data retrieved from the system and the format in which it is structured will vary, 


as follows: 
Syntax Data Retrieved Format 
DATE Current date in Gregorian form yymmdd 
DATE YYYYMMDD Current date in Gregorian form yyyymmdd 
DAY Current date in Julian form yyddd 
DAY YYYYDDD Current date in Julian form yyyyddd 
DAY-OF-WEEK Current day within a week where 1 = Mon-  d 
day.., 7 = Sunday 
TIME Time, including hundredths of a second (n) hhmmssnn 
MICROSECOND-TIME Time, including micro seconds (u) hhmmssuuuuuu 


2. When using one of --std=acu or --std=acu-strict, ACCEPT FROM TIME data- 
item with data-item providing more than 12 digits behaves as if ACCEPT FROM 
MICROSECOND-TIME data-item is used (six decimal places for fractional seconds). 


3. Consider using the standard FUNCTION FORMATTED-CURRENT-DATE if you need a high 
precision (up to eight decimal places for fractional seconds). 
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7.8.1.6. ACCEPT FROM Screen-Info 


( ACCEPT FROM Screen-Info Syntax } 


ACCEPT identifier-1 


GeO Tee Gs foie, ee } 
{ COLS| COLUMNS } 
pales aaa ae } 
{ ESCAPE KEY } 


This format of the ACCEPT statement is used to retrieve information about the console 
window or about the user’s interactions with it. 

1. The reserved words LINES and LINE-NUMBER are interchangeable. 

2. The reserved words COLS and COLUMNS are interchangeable. 

3. The following points pertain to the use of the LINES and COLUMNS options: 

A. The LINES and COLUMNS options will retrieve the respective components of the 
size of the console display. 

B. When the console is running in a windowed environment, this will be the sizing of 
the window in which the program is executing, in terms of horizontal (COLUMNS) 
or vertical (LINES) character counts — not pixels. 

C. When the system is not running a windowing environment, the physical console 
screen attributes will be returned. 

D. Values of 0 will be returned if GnuCOBOL was not generated to include screen 
EO: 

E. See the documentation on the CBL_GET_SCR_SIZE built-in system subroutine (see 
[(CBL_GET_SCR_SIZE], page 581) for another way to retrieve this information. 


4. The ESCAPE KEY option may be used after the ACCEPT FROM Screen-Info statement 
(see [ACCEPT FROM Screen-Info], page 280) has executed. The result returned will 
be the four-digit CRT STATUS (see [SPECIAL-NAMES], page 92) identifier value. See 
[CRT STATUS Codes], page 275, for the specific code values. 
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7.8.1.7. ACCEPT FROM Runtime-Info 


[ 


ACCEPT FROM Runtime-Info Syntax 


ACCEPT identifier-1 


FN A ea } 


This format of the ACCEPT statement is used to retrieve run-time information such as the 
most-recent error exception code and the current user’s user name. 


1. The following points pertain to the use of the EXCEPTION STATUS option: 


A. 
B. 


C. 


identifier-1 must be defined as a PIC X(4) item. 
See [Error Exception Codes], page 447, for a complete list of the exception codes 
and their meanings. 


An alternative to the use of ACCEPT FROM Runtime-Info is to use the 
EXCEPTION-STATUS intrinsic function (see [EXCEPTION-STATUS], page 447). 


2. The following points pertain to the use of the USER NAME option: 


A. 


The returned result is the userid that was used to login to the system with, and 
not any actual first and/or last name of the user in question (unless, of course, 
that is the information used as a logon id). It is not the PID or UID numbers but 
the name associated with the UID under *nix based systems. 


identifier-1 should be defined large enough to receive the longest user-name on the 
system. 


If insufficient space is allocated, the returned value will be truncated. 


If excess space is allocated, the returned value will be padded with spaces (to the 
right). 
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7.8.1.8. ACCEPT OMITTED 


ACCEPT OMITTED Syntax 


ACCEPT OMITTED 


ab For console : See 6.17.1.1 (ACCEPT FROM CONSOLE Syntax) 
2. For Screen : See 6.17.1.4 (ACCEPT screen-data-item Syntax) 


[ END-ACCEPT ] 


This format of the ACCEPT statement will wait for a keyboard event that terminates input; 
function keys, or Enter/Return, among others. CRT STATUS (COB-CRT-STATUS CRT 
STATUS (see [SPECIAL-NAMES], page 92) if not explicitly defined) is set with the keycode, 
listed in copy/screenio.cpy. It also handles a few other keycode terminations not normally 
used to complete an extended accept. 
1. The following are examples of keycodes that can be used: 

COB-SCR-INSERT 

COB-SCR-DELETE 

COB-SCR-BACKSPACE 

COB-SCR-KEY-HOME 

COB-SCR-KEY-END 


2. You can used extended attributes, useful for setting timeouts or positioning. 
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7.8.1.9. ACCEPT FROM EXCEPTION STATUS 


ACCEPT FROM EXCEPTION STATUS Syntax ] 


ACCEPT exception-status-pic-9-4 FROM EXCEPTION STATUS 


This format of the ACCEPT statement will receive the status for any exceptions resulting 
from a previous valid verb. 
1. The following is an example of usage: 


In WS: 
01 exception-status pic 9(4). 


In PD: 


ACCEPT unexpected-rounding FROM EXCEPTION STATUS 
IF unexpected-rounding NOT EQUAL "0000" THEN 
DISPLAY "Unexpected rounding. Code " unexpected-rounding 
UPON SYSERR 
END-IF 
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7.8.2. ADD 


7.8.2.1. ADD TO 


ADD TO Syntax } 


ADD { literal-1 Le 
~~~ { identifier-1 } 


TO { identifier-2 
[ ROUNDED [ MODE IS { AWAY-FROM-ZERO +] J}... 
nag eee ye ra ni } 


wy 


A 
2g 
z 
2g 
zg 
z 
zg 
2g 
2g 
2g 
2g 
Peery YyYYYYwy 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-ADD ] 


This format of the ADD statement generates an intermediate arithmetic sum of the values of 
all identifier-1 and literal-1) items. The value of each identifier-2 will be replaced, in turn, 
by the sum of that identifier-2s value and the intermediate sum. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items while literal-1 
must be a numeric literal. 


3. An identifier-1 data item may also be coded as an identifier-2. Note, however, that the 
value of such a data item will therefore be included twice in the result. 
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4. The contents of each identifier-1 will remain unchanged by this statement. 

5. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 
will control how non-integer results will be saved. 

6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERRORI, page 261, for additional information. 
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7.8.2.2. ADD GIVING 


ADD GIVING Syntax 


ADD { literal-1 Peas 
~~~ { identifier-1 } 


{ TO identifier-2 ] 


GIVING { identifier-3 


ro) 
ws 
ws 
ro) 


[ ROUNDED [ MODE IS { AWAY-FROM-ZERO 
Cedededieadieadiod n~nwnwe { www nwnwnwnwnwnwnwnwnwnwwe 


YY YY YY 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-ADD ] 


This format of the ADD statement generates the arithmetic sum of the values of all identifier- 
1, literal-1) and identifier-2 (if any) items and then saves that sum to each identifier-3. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items while literal-1 
must be a numeric literal; identifier-3 may be either a numeric or numeric edited data 
item. 


3. An identifier-1 or identifier-2 data item may be used as an identifier-3, if desired. 


4. The contents of each identifier-1 and identifier-2 will remain unchanged by this state- 
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ment, unless they happen to also be specified as an identifier-3. 

5. The current value in each identifier-3 at the start of the statement’s execution is irrele- 
vant, since the contents of each identifier-3 will simply be replaced with the computed 
sum. 

6. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-3 
will control how non-integer results will be saved. 

7. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-3 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


288 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


7.8.2.3. ADD CORRESPONDING 


ADD CORRESPONDING Syntax 


ADD CORRESPONDING identifier-1 


TO identifier-2 
{ ROUNDED [ MODE IS { AWAY-FROM-ZERO 
wn nnnnne n~nwnwn { dada dade dieadiadie die diediediediadiod 


wy 
a 
a 


wy 


A 

z 

z 

z 

2g 

zg 

2g 

2g 

2g 

2g 

2g 
PPM Y YY 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-ADD ] 


This format of the ADD statement generates code equivalent to individual ADD TO (see [ADD 
TO], page 284) statements for corresponding matches of data items found subordinate to 
the two identifiers. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 

2. Both identifier-1 and identifier-2 must be group items. 

3. See [CORRESPONDING], page 258, for information on how corresponding matches 
will be found between identifier-1 and identifier-2. 

4. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-3 
will control how non-integer results will be saved. 


5. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
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this case, failure is defined as being an identifier-3 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 
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7.8.3. ALLOCATE 


ALLOCATE Syntax 


FORMAT 1. ALLOCATE a "BASED" ITEM. 


ALLOCATE identifier-1 


[{ INITIALIZED } ] [ RETURNING identifier-3 ] 


Le eae Seri pale RSs 
[{ INITIALISED } ] 
5 Calero ocsceetes } ] 


FORMAT 2. ALLOCATE a memory block. 


ALLOCATE arithmetic-expression-1 CHARACTERS 


[{ INITIALIZED } [ TO { identifier-2}] ] RETURNING identifier-3 


Fe Pe ere sl Rusia A) ro 
[{ INITIALISED } [ { literal-1 }] ] 
en eee } ] 


The ALLOCATE statement is used to dynamically allocate memory at run-time. 


1. 
2. 


The reserved words INITIALIZED and INITIALISED are interchangeable. 


If data-name-1 is specified, the RETURNING phrase may be omitted; otherwise, the 
RETURNING phrase shall be specified. 

If used, expression-1 must be an arithmetic expression with a non-zero positive integer 
value and the RETURNING phrase must be specified. 

If used, identifier-1 should be an 01-level item defined in working-storage or local- 
storage with the BASED (see [BASED], page 160) attribute. It may be an 01 item 
defined in the linkage section without the BASED attribute, but using such a data item 
is not recommended. 


If used, identifier-3 should be a POINTER (see [USAGE], page 232) data item. 


. The optional RETURNING clause will return the address of the allocated memory block 


into the specified USAGE POINTER identifier-3 data item. When this option is used, 
knowledge of the originally-requested size of the allocated memory block will be retained 
by the program in case a FREE (see [FREE], page 331) statement is ever issued against 
identifier-3. 


When the identifier-1 option is used in conjunction with INITIALIZED (or its inter- 
nationalized alternative INITIALISED), the allocated memory block will be initialized 
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10. 


11. 


as if an INITIALIZE identifier-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT (see 
[INITIALIZE], page 339) were executed. 


When the expression-1 CHARACTERS option is used, INITIALIZED will initialize the 
allocated memory block to binary zeros. If INITIALIZED is not used, the initial contents 
of allocated memory will be left to whatever rules of memory allocation are in effect 
for the operating system the program is running under. 


There are two basic ways in which this statement is used. The simplest is: 
ALLOCATE My-01-Item 


With this form, a block of storage equal in size to the defined size of My-01-Item (which 
must have been defined with the BASED attribute) will be allocated. The address of 
that block of storage will become the base address of My-01-Item so that it and its 
subordinate data items become usable within the program. 


A second (and equivalent) approach is: 


ALLOCATE LENGTH OF My-01-Item CHARACTERS RETURNING The-Pointer 
SET ADDRESS OF My-01-Item TO The-Pointer 


With this form My-01-Item can either be defined with the BASED attribute or be defined 
in LINKAGE SECTION. Instead of LENGTH OF My-01-Item you may also use a size 
smaller to the maximum field size as long as you ensure that the complete field is never 
used. 


Referencing a BASED data item either before its storage has been allocated or after its 
storage has been released (via the FREE statement) will lead to “unpredictable results” . 
That’s how reference manuals and standards specifications talk about this situation. 
In the author’s experience, the results are all too predictable: the program aborts from 
an attempt to reference an unallocated area of memory. 
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7.8.4. ALTER 


ALTER Syntax 


ALTER procedure-name-1 TO PROCEED TO procedure-name-2 


The ALTER statement was used in the early years of the COBOL language to edit the object 
code of a program at execution time, changing a GO TO (see [Simple GO TO], page 335) 
statement to branch to a spot in the program different than where the GO TO statement was 
originally compiled for. 


1. 


The reserved words PROCEED and TO (the one after PROCEED) are optional and may be 
omitted. The presence or absence of these words has no effect upon the program. 


procedure-name-1 must contain only a single statement, and that statement must be 
a simple GO TO. 


The effect of this statement will be as if the generated machine-language code for the GO 
TO statement in procedure-name-! is changed so that the GO TO statement now transfers 
control to procedure-name-2, rather than to whatever procedure name was specified in 
the program source code. 

Support for the ALTER verb has been added to GnuCOBOL for the purpose of enabling 
GnuCOBOL to pass those National Institute of Standards and Technology (NIST) tests 
for the COBOL programming language that require support for ALTER. 

Because of the catastrophic effect this statement has on program readability and there- 
fore the programmer’s ability to debug problems with program logic, the use of ALTER 
in new programs is STRONGLY discouraged. 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 293 


7.8.5. CALL 


CALL Syntax 


CALL [ { STDCALL } ] { literal-1 } 
epee ~ Es goa } { identifier-1 } 
{ STATIC } 
Ay Dew ae } 
{ mnemonic-name-1 } 


[ USING CALL-Argument... ] 


[ NOT ON OVERFLOW|EXCEPTION imperative-statement-2 ] 


[ END-CALL ] 


CALL Argument Syntax 


[ BY { REFERENCE } ] 


fear rere 4 } 
{ CONTENT } 
scene } 
{ VALUE } 
{ OMITTED 3 
[ crreeee } 
{ [ UNSIGNED ] [ SIZE IS { AUTO } 1 £4 literai=2 - +} 
amare wa mm pees } { identifier-2 } 
{ DEFAULT } 
gE ete eric } 
{ integer-1 } 


The CALL statement is used to transfer control to a subroutine. See [Sub-Programming], 
page 675, for the specifics of using subprograms with GnuCOBOL programs. 


1. The reserved words BY, IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 
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2. The reserved words EXCEPTION and OVERFLOW are interchangeable. 
3. The reserved words GIVING and RETURNING are interchangeable. 


4. The expectation is that the subroutine will eventually return control back to the calling 
program, at which point the CALLing program will resume execution starting with the 
statement immediately following the CALL. Subprograms are not required to return to 
their callers, however, and are free to halt program execution if they wish. 


The mnemonic-name-1 / STATIC / STDCALL option, if used, affects the linkage con- 
ventions that will be used to the subroutine being called, as follows: 


STATIC causes the linkage to the subroutine to be performed in such a way as to re- 
quire the subroutine to be statically-linked with the calling program. Note 
that this enables static-linking to be used on a subroutine-by-subroutine 
selective basis. 

STDCALL allows system standard calling conventions (as opposed to GnuCOBOL 


calling conventions) to be used when calling a subroutine. The definition 
of what constitutes “system standard” may vary from operating system to 
operating system. Use of this requires special knowledge about the linkage 
requirements of subroutines you are intending to CALL. Subroutines written 
in GnuCOBOL do not need this option. 


mnemonic-name- 1 


allows a custom defined calling convention to be used. Such mnemonic 
names are defined using the CALL-CONVENTION (see [SPECIAL-NAMES], 
page 92) clause. That clause associates a decimal integer value with 
mnemonic-name-1 such that the individual bits set on or off in the binary 
equivalent of the integer affect linkage to the subroutine as described in 
the following chart. Those rows of the chart marked with a “No” in the 
Supported column represent bit positions (switch settings) in the integer 
value that are currently accepted (to provide compatibility to other 
COBOL implementations) if coded, but are otherwise unsupported. 


Note that bit 0 is the right-most bit in the binary value. 


Bit Supported Meaning if 0 Meaning if 1 

0 No Arguments will be passedin Arguments will be passed in 
right-to-left sequence left-to-right sequence. 

1 No The calling program will The called program (sub- 
flush processed arguments routine) will flush processed 
from the argument stack. arguments from the argu- 

ment stack. 

2 Yes The RETURN-CODE special The RETURN-CODE special 


register (see [Special Reg- 
isters], page 265) will be 
updated in addition to any 
RETURNING or GIVING data 
item. 
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dated (but any RETURNING 
or GIVING data item still 
will). 
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3 Yes If CALL literal is used, If CALL literal is used, 
the subroutine will be lo- the subroutine can only be 
cated and linked in with located and linked with the 
the calling program at com- calling program at compila- 
pile time or may be dynam- _ tion time. 
ically located and loaded 
at execution time, depend- 
ing on compiler switch set- 
tings and operating system 
capabilities. 

4 No OS/2 “OPTLINK” conven- OS/2 “OPTLINK” conven- 
tions will not be used to tions will be used to CALL 
CALL the subprogram. the subprogram. 

5 No Windows 16-bit “thunking” Windows 16-bit “thunking” 
will not be in effect. will be used to call the sub- 

routine as a DLL. 
6 Yes The STDCALL convention The STDCALL convention, 


will not be used. 


required to use the Mi- 
crosoft Win32 API, will be 
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used. 


Using the STATIC option on a CALL statement is equivalent to using 
CALL-CONVENTION 8 (only bit 3 set). 


Using the STDCALL option on a CALL statement is equivalent to using CALL 
CONVENTION 64 (only bit 6 set). 


. The value of literal-1 or identifier-1 is the entry-point of the subprogram you wish to 
call. 


. When you call a subroutine using identifier-1, you are forcing the runtime system to call 
a dynamically-loadable subprogram. The contents of identifier-1 will be the entry-point 
name within that module. If this is the first call to any entry-point within the module 
being made at run-time, the contents of identifier-1 must be the primary entry-point 
name of the module (which must also match the filename, minus any OS-mandated 
extension) of the executable file comprising the module). 


. You can force the GnuCOBOL runtime system to pre-load all dynamically-loaded mod- 
ules that could ever be called by the program, at the time the program starts executing. 
This is accomplished through the use of the COB_PRE_LOAD run-time environment vari- 
able (see [Run Time Environment Variables], page 654). If used, this will only pre-load 
those modules invoked via CALL literal-1, as the runtime contents of identifier-1 
cannot be predicted. 


. If the subprogram being called is a GnuCOBOL program, and if that program had 
the INITIAL (see IDENTIFICATION DIVISION], page 85) attribute specified on its 
PROGRAM-ID clause, all of the subprogram’s data division data will be restored to its 
initial state each time the subprogram is executed, regardless of which entry-point 
within the subprogram is being referenced. 
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This [re]-initialization behaviour will always apply to any subprogram’s local-storage 
(if any), regardless of the use (or not) of INITIAL. 


The USING clause defines a list of arguments that may be passed from the calling 
program to the subprogram. The manner in which any given argument is passed to the 
subroutine depends upon the BY clause (if any) coded (or implied) for that argument, 
as follows: 


BY REFERENCE 
passes the address of the argument to the subprogram. If the subprogram 
changes the contents of that argument, the change will be “visible” to the 
calling program. 


BY CONTENT 
passes the address of a copy of the argument to the subprogram. If the 
subprogram changes the value of such an argument, the change only affects 
the copy back in the calling program, not the original version. 


BY VALUE passes the actual numeric value of the literal or identifiers contents as the 
argument. This feature exists to provide compatibility with C, C++ and 
other languages and would not normally be used when calling GnuCOBOL 
subprograms. Only numeric literals or numeric data items should be passed 
in this manner. 


If an argument lacks a BY clause, the most-recently encountered BY specification on 
that CALL statement will be assumed. If the first argument specified on a CALL lacks a 
BY clause, BY REFERENCE will be assumed. 


No more than 251 arguments may be passed to a subroutine, unless the GnuCOBOL 
compiler was built with a specifically different argument limit specified for it. If you 
have access to the GnuCOBOL source code, you may adjust this limit by changing the 
value of the COB_LMAX_FIELD_PARAMS in the call.c file (found in the libcob folder) as 
well as the last shown #if MAX_CALL_FIELD_PARAMS statement before you run make to 
build the compiler and run-time library. 


The RETURNING clause allows you to specify a numeric data item into which the subrou- 
tine should return a numeric value. If you use this clause on the CALL, the subroutine 
should include a RETURNING (see [PROCEDURE DIVISION RETURNING], page 252) 
clause on its procedure division header. Of course, a subroutine may pass a value of 
any kind back in any argument passed BY REFERENCE. 


The optional ON OVERFLOW and NOT ON OVERFLOW clauses (or ON EXCEPTION and NOT ON 
EXCEPTION — they are interchangeable) may be used to detect and react to the failure 
or success, respectively, of an attempt to CALL the subroutine. Failure, in this context, 
is defined as the inability to either locate or load the object code of the subroutine 
at execution time. See [ON OVERFLOW + NOT ON OVERFLOW\, page 260, for 


additional information. 


Call also supports using an entry point stored in a PROGRAM-POINTER, avoiding 
the dynamic runtime lookup. GnuCOBOL keeps a cache of lookups during a 
program run. Repeated use of a named function does not suffer much penalty, but 
PROGRAM-POINTER will be just that little bit faster. To set a PROGRAM-POINTER use 
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SET program-reference TO ENTRY "name" (or get the address from an API, and take 
part in callback programming). 

15. An extension of CALL allows a call to a Program-Pointer-1 which is preset using SET 
program-pointer-1 TO ENTRY x. Additional the RETURNING clause may return a data 
pointer or a PROGRAM-POINTER 
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7.8.6. CANCEL 


CANCEL Syntax ] 


CANCEL { literal-1 }... 
eg ies { identifier-1 } 


The CANCEL statement unloads the dynamically-loadable subprogram module containing 
the entry-point specified as literal-1 or identifier-1 from memory. 

1. If a dynamically-loadable module unloaded by the CANCEL statement is subsequently 
re-executed, all data division storage for that module will once again be in its initial 
state. 

2. Whether the CANCEL statement actually physically unloads a dynamically-loaded mod- 
ule or simply marks it as logically-unloaded depends on the use and value of the 

COB_PHYSICAL_CANCEL run-time environment variable (see [Run Time Environment 
Variables], page 654). 
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7.8.7. CLOSE 


CLOSE Syntax 


CLOSE { file-name-1 [ { REEL|UNIT [ FOR REMOVAL ] } ] }... 


aS Slee oer ae oy ere Te 
{ WITH LOCK } 
- areca } 
{ WITH NO REWIND } 


The REEL, LOCK and NO REWIND clauses are syntactically recognized but are otherwise non- 
functional, except for the CLOSE. ..NO REWIND statement, which will generate a file status 
of 07 rather than the usual 00 (but take no other action). 


The CLOSE statement terminates the program’s access to the specified file(s). 


1. The reserved words FOR and WITH are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. The reserved words REEL and UNIT are interchangeable. 


3. The CLOSE statement may only be executed against files that have been successfully 
opened. 


4. A successful CLOSE will write any remaining unwritten record buffers to the file (similar 
to an UNLOCK statement (see [UNLOCK], page 412)) and release any file locks for the file, 
regardless of open mode. A closed file will then be no longer available for subsequent 
I/O statements until it is once again OPENED. 

5. When a ORGANIZATION LINE SEQUENTIAL (see [ORGANIZATION LINE SEQUEN- 
TIAL], page 111) or LINE ADVANCING (see [LINE ADVANCING], page 15) file is 
closed, a final delimiter sequence will be written to the file to signal the termination 
point of the final data record in the file. This will only be necessary if the final record 
written to the file was written with the AFTER ADVANCING (see [WRITE], page 417) 
option. 
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7.8.8. COMMIT 


COMMIT Syntax 


COMMIT 


The COMMIT statement performs an UNLOCK against every currently-open file, but does not 
close any of the files. See the UNLOCK statement (see [UNLOCK], page 412) for additional 
details. 
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7.8.9. COMPUTE 


COMPUTE Syntax 


COMPUTE { identifier-1 
[ ROUNDED [ MODE IS { AWAY-FROM-ZERO 
 edededadadod n~nwwe { wn nwnwnwnwnwnwnwnwnwnwnwwe 


j oe | 
WY 


A 
z 
zg 
zg 
2g 
2 
2 
zg 
a 
a 
z 
2g 
2g 
zg 
zg 
zg 
z 
z 
2g 
2g 

WS YY YY YY YY Ye 


rm 
fo) 
a2 
wn 
HH. 
N 
ica) 
ea 
w 
=) 
fo) 
ee) 
H- 
B 
ue) 
oO 
4 
ry) 
ct 
H- 
<q 
0) 
| 
n 
ct 
wy) 
ct 
(0) 
B 
0) 
Bb 
- 
bE 
| or 


rm 


NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-COMPUTE ] 


The COMPUTE statement provides a means of easily performing complex arithmetic opera- 
tions with a single statement, instead of using cumbersome and possibly confusing sequences 
of ADD, SUBTRACT, MULTIPLY and DIVIDE statements. COMPUTE also allows the use of expo- 
nentiation — an arithmetic operation for which no other statement exists in COBOL. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. The reserved word EQUAL is interchangeable with the use of ‘=’. 
3. Each identifier-1 must be a numeric or numeric-edited data item. 


4. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-1 
will control how non-integer results will be saved. 


5. See [Arithmetic Expressions], page 42, for more information on arithmetic expressions. 
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6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined either as having an identifier-3 with an insufficient number of 
digit positions available to the left of any implied decimal point or attempting to divide 
by zero. See [ON SIZE ERROR + NOT ON SIZE ERROR], page 261, for additional 


information. 
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7.8.10. CONTINUE 


CONTINUE Syntax } 


CONTINUE 


{ identifier-1 } 
CONTINUE AFTER { literal-1 + SECONDS 
{ arithmetic-expression-1 } ~“"~~"~* 


The CONTINUE statement is a no-operation statement that may be coded anywhere an 
imperative statement (see [Imperative Statement], page 718) may be coded. 

1. The CONTINUE statement has no effect on the execution of the program. 

2. This statement (perhaps in combination with an appropriate comment or two) makes 
a convenient “place holder” — particularly in ELSE (see [IF], page 338) or WHEN (see 
[EVALUATE], page 320) clauses where no code is currently expected to be needed, but 
a place for code to handle the conditions in question is to be reserved in case it’s ever 
needed. 

3. The optional extension of (AFTER) when used with the CONTINUE statement pauses 
execution for a specified length of time. 
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7.8.11. DELETE 


DELETE Syntax 


DELETE file-name-1 RECORD 


The DELETE statement logically deletes a record from a COBOL file. 


1. 


The reserved words KEY and RECORD are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


The ORGANIZATION of file-name-1 cannot be ORGANIZATION LINE SEQUENTIAL (see 
[ORGANIZATION LINE SEQUENTIAL], page 111). 


The file-name-1 file cannot be a sort/merge work file (a file described using a SD (see 
[File/Sort-Description], page 124)). 

For files in the SEQUENTIAL access mode, the last input-output statement executed 
against file-name-1 prior to the execution of the DELETE statement must have been 
a successfully executed sequential-format READ statement (see [Sequential READ}, 
page 366). That READ will therefore identify the record to be deleted. 


If file-name-1 is a RELATIVE file whose ACCESS MODE (see [ORGANIZATION RELA- 
TIVE], page 113) is either RANDOM or DYNAMIC, the record to be deleted is the one whose 
relative record number is currently the value of the field specified as the files RELATIVE 
KEY in its SELECT statement. 

If file-name-1 is an INDEXED file whose ACCESS MODE (see [ORGANIZATION 
INDEXED], page 115) is RANDOM or DYNAMIC, the record to be deleted is the one 
whose primary key is currently the value of the field specified as the RECORD KEY in 
the file’s SELECT statement. 

The optional INVALID KEY and NOT INVALID KEY clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to delete a record. See 
(INVALID KEY + NOT INVALID KEY], page 259, for additional information. 

No INVALID KEY or NOT INVALID KEY clause may be specified for a file who’s ACCESS 
MODE IS SEQUENTIAL. 
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7.8.12. DISPLAY 
7.8.12.1. DISPLAY UPON device 


DISPLAY UPON device Syntax ] 


DISPLAY { literal-1 A eae 
gine Figees { identifier-1 } 
[ UPON mnemonic-name-1 ] 


[ WITH NO ADVANCING ] 


[ NOT ON EXCEPTION imperative-statement-2 ] 


[ END-DISPLAY ] 


This format of the DISPLAY statement displays the specified identifier contents and/or literal 
values on the system output device specified via the UPON clause. 


1. The reserved words ON and WITH are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. If no UPON clause is specified, UPON CONSOLE will be assumed. If the UPON clause is 
specified, mnemonic-name-1 must be one of the built-in output device names CONSOLE, 
PRINTER, STDERR, STDOUT, SYSERR, SYSLIST, SYSLST or SYSOUT or a mnemonic name 
assigned to one of those devices via the SPECIAL-NAMES (see [SPECIAL-NAMES], 
page 92) paragraph. 


When displaying upon the STDERR or SYSERR devices or to a mnemonic-name-1 attached 
to one of those two devices, the output will be written to output pipe #2, which will 
normally cause the output to appear in the console output window. You may, if desired, 
redirect that output to a file by appending 2> filename to the end of the command 
that executes the program. This applies to both Windows (any type) or Unix versions 
of GnuCOBOL. 


When displaying upon the CONSOLE, PRINTER, STDOUT, SYSLIST, SYSLST or SYSOUT 
devices or to a mnemonic-name-1 attached to one of them, the output will be written 
to output pipe #1, which will normally cause the output to appear in the console 
output window. You may, if desired, redirect that output to a file by appending 1> 
filename or simply > filename to the end of the command that executes the program. 
This applies to both Windows (any type) or Unix versions of GnuCOBOL. 


3. The NO ADVANCING clause, if used, will suppress the carriage-return / line-feed sequence 
that is normally added to the end of any console display. 
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4. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to display output to the 
specified device. See [ON EXCEPTION + NOT ON EXCEPTION], page 260, for 


additional information. 
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7.8.12.2. DISPLAY UPON COMMAND-LINE 


DISPLAY UPON COMMAND-LINE Syntax 


DISPLAY { literal-1 J... 

ee ee { identifier-1 } 
UPON { ARGUMENT-NUMBER|COMMAND-LINE } 
PL Eig So ety ee OS MSR SN EG DE Sa } 


[ NOT ON EXCEPTION imperative-statement-2 ] 


[ END-DISPLAY ] 


This form of the DISPLAY statement may be used to specify the command-line argu- 
ment number to be retrieved by a subsequent ACCEPT FROM ARGUMENT-VALUE statement 
(see [ACCEPT FROM COMMAND-LINE}, page 269) or to specify a new value for the 
command-line arguments themselves. 

1. The reserved word ON is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 

2. By displaying a numeric integer value UPON ARGUMENT-NUMBER, you will specify which 
argument (by its relative number) will be retrieved by a subsequent ACCEPT FROM 
ARGUMENT-VALUE statement. 

3. Executing a DISPLAY UPON COMMAND-LINE will influence subsequent ACCEPT FROM 
COMMAND-LINE statements (which will then return the value you displayed), but will 
not influence subsequent ACCEPT FROM ARGUMENT-VALUE statements — these will 
continue to return the original program execution parameters. 

4. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to display output to the spec- 
ified item. See [ON EXCEPTION + NOT ON EXCEPTION], page 260, for additional 


information. 
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7.8.12.3. DISPLAY UPON ENVIRONMENT-NAME 


[ 


DISPLAY UPON ENVIRONMENT-NAME Syntax } 
DISPLAY { literal-1 }... UPON { ENVIRONMENT-VALUE } 
ek { identifier-1 } Be aie) Sage eee pao oe 


[ NOT ON EXCEPTION imperative-statement-2 ] 


END-DISPLAY ] 


This form of the DISPLAY statement can be used to create or modify environment variables. 


1. 


The reserved word ON is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


To create or change an environment variable will require two DISPLAY statements. 
The following example sets the environment variable MY_ENV_VAR to a value of 
‘Demonstration Value’: 

DISPLAY "MY_ENV_VAR" UPON ENVIRONMENT-NAME 

DISPLAY "Demonstration Value" UPON ENVIRONMENT-VALUE 
Environment variables created or changed from within GnuCOBOL programs will be 
available to any sub-shell processes spawned by that program (i.e. CALL ’SYSTEM’ 
(see [SYSTEM], page 595)) but will not be known to the shell or console window that 
started the GnuCOBOL program. 
Consider using SET ENVIRONMENT (see [SET ENVIRONMENT], page 382) in lieu of 
DISPLAY to set environment variables as it is much simpler. 
The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to display output to the spec- 
ified item. See [ON EXCEPTION + NOT ON EXCEPTION], page 260, for additional 


information. 
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7.8.12.4. DISPLAY Data-Item 


DISPLAY Data-Item Syntax 


DISPLAY identifier-1 [ UPON CRT|CRT-UNDER ] 


OMITTED 
[ AT { | LINE NUMBER { integer-1 } ie ae 
scalar cca { identifier-2 } | } 
{ | COLUMN|COL|POSITION|POS NUMBER { integer-2 } 
Hes SRO ee ae ery sete, ee { identifier-3 } 
se } 
{ { integer-3 } } 
{ { identifier-4 } Hs 
[ WITH [ Attribute-Specification ]... 
[ SCROLL { UP } [ { integer-4 } LINE|LINES ] ] 
er oie {~~  } { identifier-5 } 
{ DOWN } 


[ SIZE { integer-5 } 
~~~~ £ identifier-6 } ] 
[ NO ADVANCING ] 


[ NOT ON EXCEPTION imperative-statement-2 ] 


[ END-DISPLAY ] 


The UPON CRT, UPON CRT-UNDER and CONVERSION clauses are syntactically recognized but 
are otherwise non-functional. They are supported to provide compatibility with COBOL 
source written for other COBOL implementations. 


This format of the DISPLAY statement presents data onto a formatted screen. 


1. The reserved words AFTER, LINE, LINES, NUMBER and ON are optional and may be 
omitted. The presence or absence of these words has no effect upon the program. 


2. The reserved words COLUMN and POSITION are interchangeable. 
3. The reserved words LINE and LINES are interchangeable. 


4. If identifier-1 is defined in the SCREEN SECTION (see [SCREEN SECTION], page 143), 
any AT, Attribute-Specification and WITH clauses will be ignored. All field definition, 
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cursor positioning and screen control will occur as a result of the screen section defini- 
tion of identifier-1. 


5. The reserved word OMITTED when used, will act to position the cursor or any screen 
clearance without changing any content of the screen. 


6. The following points apply if identifier-1 is not defined in the screen section: 


A. The purpose of the AT clause is to define where on the screen identifier-1 should 
be displayed. See [ACCEPT data-item], page 272, for additional information. 

B. The purpose of the WITH clause is to define the visual attributes that should be ap- 
plied to identifier-1 when it is displayed on the screen as well as other presentation- 
control characteristics. 

C. The following Attribute-Specification clauses are allowed on the DISPLAY statement 
— these are the same as those allowed for SCREEN SECTION data items. A particular 
Attribute-Specification may be used only once in any DISPLAY: 


D. See 


BACKGROUND-COLOR (see [BACKGROUND-COLOR], page 158) 
BEEP (see [BEEP], page 161), BELL (see [BELL], page 162) 
BLANK (see [BLANK], page 163) 

BLINK (see [BLINK], page 165) 

ERASE (see [ERASE], page 170) 

FOREGROUND-COLOR (see [FOREGROUND-COLOR], page 173) 
HIGHLIGHT (see [HIGHLIGHT], page 178) 

LOWLIGHT (see [LOWLIGHT], page 186) 

OVERLINE (see [OVERLINE], page 193) 

REVERSE-VIDEO (see [REVERSE-VIDEO], page 207) 
UNDERLINE (see [UNDERLINE], page 229) 

[ACCEPT data-item], page 272, for additional information on the other WITH 


clause options. 


7. The optional ON EXCEPTION and NOT ON EXCEPTION clauses may be used to detect and 
react to the failure or success, respectively, of the screen I/O attempt. See [ON EX- 
CEPTION + NOT ON EXCEPTION], page 260, for additional information. 


When DISPLAY is used with Line and column where multiple variables or literals are 
used before LINE only the first will be displayed. 

If this is needed then the use of CONCATENATE to built more than one element together 
prior to the display, e.g., DISPLAY FUNCTION CONCATENATE (VARS-1 VARS-2) AT 0201. 

When DISPLAY is used without line or column controls only one variable or literal may 
will appear on a line, so the use of the above example should also be employed. 
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7.8.12.5. DISPLAY data-item 


( DISPLAY data-item Syntax 


DISPLAY [position-spec] {identifier-2 | literal-1} ... 


[ WITH [ Attribute-Specification ]... 

[ ERASE { SCREEN|LINE } ] 

[ SCROLL { UP } [ { integer-3 } LINE|LINES ] ] 
tet ras {~~ } { identifier-3 } 

{ DOWN } 

[ SIZE { integer-4 } 

~~~~  identifier-4 } ] 
[ END-DISPLAY ] 


where position-spec is 

{ (position-spec-num, position-spec-num) } 
{ (,position-spec-num) } 
{ (position-spec-nun, ) } 


where position-spec-num is 
{ identifier-1 } [{ + } integer-1 ] 
{ integer-2 + [{ - } ] 


This format of the DISPLAY statement presents data onto a formatted screen using the 
Microsoft format from v1 and v2 compilers (MsDos). 
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7.8.13. DIVIDE 
7.8.13.1. DIVIDE INTO 


( DIVIDE INTO Syntax 


DIVIDE { literal-1 } INTO { literal-2 
Teg, tes { identifier-1 } ~~~~ { identifier-2 } 


[ ROUNDED [ MODE IS { AWAY-FROM-ZERO 


ep arre pee t 


} GIVING { identifier-3 


wW 
= | 
‘bal 


tans 


w 


= 
ea 
> 
Dy 
[ea 
n 
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> 
= 
> 
i 
yy 
a) 
Oo 
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N 
eal 
a) 
=) 
Ww 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-DIVIDE ] 


Ww 


PPP YY YY ey 


For further clarification, the following examples are provided to be used with 
the various flavours of the DIVIDE statement when using BY, INTO and GIVING. 
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DIVIDE A INTO B GIVING C REMAINDER D | A | B_ | Integer(B/A) | Integer remainder | 
~------------------------------------- os 


This format of the DIVIDE statement will divide a numeric value (specified as a literal or 
numeric data item) into another numeric value (also specified as a literal or numeric data 
item) and will then replace the contents of one or more receiving data items with the results 
of that division. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items and literal-1 
must be a numeric literal. 


3. A division operation will be performed for each identifier-2, in turn. Each of the results 
of those divisions will be saved to the corresponding identifier-2 data item(s). 


4. Should any identifier-2 be an integer numeric data item, the result computed when 
that identifier-2 is divided by literal-1 or identifier-1 will also be an integer — any 
remainder from that division will be discarded. 

5. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 
will control how non-integer results will be saved. 

6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being numeric truncation caused by an identifier-2 with 
an insufficient number of digit positions available to the left of any implied decimal 
point, or an attempt to divide by zero. See [ON SIZE ERROR + NOT ON SIZE 
ERROR], page 261, for additional information. 
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7.8.13.2. DIVIDE INTO GIVING 


DIVIDE INTO GIVING Syntax 


DIVIDE { literal-1 } INTO { literal-2 } GIVING { identifier-3 
Oe conan { identifier-1 } ~~~~ { identifier-2 } ~~~~~~ 

{ ROUNDED [ MODE IS { AWAY-FROM-ZERO bess 
wn nnnwnne n~nnwn { da da dade diadiadie die diediediediadiod 
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[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-DIVIDE ] 


This format of the DIVIDE statement will divide one numeric value (specified as a literal or 
numeric data item) into another numeric value (also specified as a literal or numeric data 
item) and will then replace the contents of one or more receiving data items with the results 
of that division. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items while both 
identifier-3 and identifier-4 must be numeric (edited or unedited) data items. 


3. Both literal-1 and literal-2 must be numeric literals. 


4. If the REMAINDER clause is coded, there may be only one identifier-3 specified. 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 315 


5. The result obtained when the value of literal-2 or identifier-2 is divided by the value 
of literal-1 or identifier-1 is computed; this result is then moved into each identifier-3, 
in turn, applying the rules defined by the ROUNDED (see [ROUNDED], page 261) clause 
(if any) for that identifier-3 to the move. 


6. If a REMAINDER clause is specified, the value of the one and only identifier-3 (as stated 
earlier, if REMAINDER is specified there may only be a single identifier-3 coded on the 
statement) after it was assigned a value according to the previous rule will be multiplied 
by the value of literal-1 or identifier-1; that result is then subtracted from the value of 
literal-2 or identifier-2 and that result is the value which is moved to identifier-4. 

7. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point, or an attempt to divide 
by zero. See [ON SIZE ERROR + NOT ON SIZE ERROR], page 261, for additional 


information. 
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7.8.13.3. DIVIDE BY GIVING 


DIVIDE BY GIVING Syntax 


DIVIDE { literal-1 } BY { literal-2 } GIVING { identifier-3 
Oe conan { identifier-1 } ~~ { identifier-2 } ~~~~"~ 


Ww 
je | 
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[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-DIVIDE ] 


This format of the DIVIDE statement will divide one numeric value (specified as a literal 
or numeric data item) by another numeric value (also specified as a literal or numeric data 
item) and will then replace the contents of one or more receiving data items with the results 
of that division. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items while both 
identifier-3 and identifier-4 must be numeric (edited or unedited) data items. 


3. Both literal-1 and literal-2 must be numeric literals. 


4. If the REMAINDER clause is coded, there may be only one identifier-3 specified. 
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5. The result obtained when the value of literal-1 or identifier-1 is divided by the value 
of literal-2 or identifier-2 is computed; this result is then moved into each identifier-3, 
in turn, applying the rules defined by the ROUNDED (see [ROUNDED], page 261) clause 
(if any) for that identifier-3 to the move. 


6. If a REMAINDER clause is specified, the value of the one and only identifier-3 (as stated 
earlier, if REMAINDER is specified there may only be a single identifier-3 coded on the 
statement) after it was assigned a value according to the previous rule will be multiplied 
by the value of literal-2 or identifier-2; that result is then subtracted from the value of 
literal-1 or identifier-1 and that result is the value which is moved to identifier-4. 

7. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point, or an attempt to divide 
by zero. See [ON SIZE ERROR + NOT ON SIZE ERROR], page 261, for additional 


information. 
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7.8.14. ENTRY 


ENTRY Syntax 


ENTRY [ call-convention-phrase ] literal-1 


[ linkage-phrase ] 


[ USING ENTRY-Argument ... ] 


Format 2 (Special purpose and for GO TO ) 


ENTRY FOR GO TO literal-3 


ENTRY-Argument Syntax 


[ BY { REFERENCE } ] { OMITTED } 


eee as } 

{ CONTENT }] { [ size-phrase ] { identifier-1 } } 

{ ceeneee { literal-2 fae g 

{ VALUE } ] { [ size-phrase ] { identifier-1 } } 
uscene { literal-2 ee 


The ENTRY statement is used to define an alternate entry-point into a subroutine, along 
with the arguments that subroutine will be expecting. 


1. 


The reserved word BY is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


You may not use an ENTRY statement in a nested subprogram, nor may you use it in 
any form of user-defined function. 

The USING clause defines the arguments the subroutine entry-point supports. This list 
of arguments must match up against the USING clause of any CALL statement that will 
be invoking the subroutine using this entry-point. 

Each ENTRY-Argument specified on the ENTRY statement must be defined in the link- 
age section of the subroutine in which the ENTRY statement exists. 

The literal-1 value will specify the entry-point name of the subroutine. It must be 
specified exactly on CALL statements (with regard to the use of upper- and lower-case 
letters) as it is specified on the ENTRY statement. 

The meaning of REFERENCE, CONTENT and VALUE are the same as the equivalent spec- 
ifications on the CALL statement (see [CALL], page 293). Whatever specification will 
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be used for an argument on the CALL to this entry-point should match the specification 
used in the corresponding ENTRY-Argument. The same rules regarding the presence 
or absence of a BY clause on a CALL statement apply to the presence or absence of a BY 
clause on the corresponding argument of the ENTRY statement. 

7. The GO TO with the ENTRY FOR is an GnuCOBOL special purpose extension for 
use with various GnuCobol tools. 
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7.8.15. EVALUATE 


EVALUATE Syntax 


EVALUATE Selection-Subject-1 [ ALSO Selection-Subject-2 ]... 


{ { WHEN Selection-Object-1 [ ALSO Selection-Object-2 ] }... 


[ imperative-statement-1 ] }... 
[ WHEN OTHER 


imperative-statement-other ] 


ro 


END-EVALUATE ] 


[ EVALUATE Selection Subject Syntax 
{ TRUE } 
wee - 
{ FALSE - 
7 ae a 
{ expression-1 } 
{ identifier-1 } 
{ literal-1 } 
[ EVALUATE Selection Object Syntax 
{ ANY } 
5 el } 
{ TRUE } 
7 ees } 
{ FALSE } 
ie Ce } 
{ partial-expression-1 } 
{ } 
{ { expression-2 } [ THRU|THROUGH { expression-3 } ] } 
{ { identifier-2 } ~“"""™ 77777, { identifier-3 } } 
{ { literal-2 } { literal-3 +) 6} 
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The EVALUATE statement provides a means of defining processing that should take place 
under any number of mutually-exclusive conditions. 


1. 
2. 


9. 


The reserved words THRU and THROUGH are interchangeable. 

There must be at least one WHEN clause (in addition to any WHEN OTHER clause) specified 

on any EVALUATE statement. 

There must be at least one Selection-Subject specified on the EVALUATE statement. 

Any number of additional Selection-Subject clauses may be specified, using the ALSO 

reserved word to separate each from the prior. 

Each WHEN clause (other than the WHEN OTHER clause, if any) must have the same 

number of Selection-Object clauses as there are Selection-Subject clauses. 

When using THRU, the values on both sides of the THRU must be the same class (both 

numeric, both alphanumeric, etc.). 

A partial-expression is one of the following: 

A. A Class Condition without a leading identifier-1 (see [Class Conditions], page 46). 

B. A Sign Condition without a leading identifier-1 (see [Sign Conditions], page 48). 

C. A Relation Condition with nothing to the left of the relational operator (see 
[Relation Conditions], page 50). 

At execution time, each Selection-Subject on the EVALUATE statement will have its 

value matched against that of the corresponding Selection-Object on a WHEN clause, in 

turn, until: 

A. A WHEN clause has each of its Selection-Object(s) successfully matched by the 
corresponding Selection-Subject; this will be referred to as the ’Selected WHEN 
clause’. 

B. The complete list of WHEN clauses (except for the WHEN OTHER clause, if any) has 
been exhausted. In this case, there is no ’Selected WHEN Clause’. 

If a Selected WHEN Clause’ was identified: 

A. The imperative-statement-1 (see [Imperative Statement], page 718) immediately 
following the ’Selected WHEN Clause’ will be executed. If the ’Selected WHEN 
Clause’ is lacking an imperative-statement-1, the first imperative-statement-1 
found after any following WHEN clause will be executed. 

B. Once the imperative-statement-1 has been executed, or no imperative-statement-1 
was found anywhere after the ’Selected WHEN Clause’, control will proceed to the 
statement following the END-EVALUATE or, if there is no END-EVALUATE, the first 
statement that follows the next period. If, however, the imperative-statement-1 
included a GO TO statement, and that GO TO was executed, then control will transfer 
to the procedure named on the GO TO instead. 


If no ’Selected WHEN Clause’ was identified: 

A. The WHEN OTHER clause’s imperative-statement-other will be executed, if such a 
clause was coded. 

B. Control will then proceed to the statement following the END-EVALUATE or the first 
statement that follows the next period if there is no END-EVALUATE. If,however, 
the imperative-statement-other included a GO TO statement, and that GO TO was 
executed, then control will transfer to the procedure named on the GO TO instead. 
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10. In order for a Selection-Subject to match the corresponding Selection-Object on a WHEN 
clause, at least one of the following must be true: 


A. The Selection-Object is ANY 

B. The implied Relation Condition Selection-Subject = Selection Object is TRUE 
— See [Relation Conditions], page 50, for the rules on how the comparison will be 
made. 

C. The value of the Selection-Subject falls within the range of values specified by the 
THRU clause of the Selection-Object 

D. If the Selection-Object is a partial-expression, then the conditional expression that 
would be represented by coding Selection-Subject Selection-Object evaluates 
to TRUE 

11. Here is a sample program that illustrates the EVALUATE statement. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEMOEVALUATE. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 Test-Digit PIC 9(1). 
88 Digit-Is-Odd VALUE 1, 3, 5, 7, 9. 
88 Digit-Is-Prime VALUE 1, 3, 5, 7. 
PROCEDURE DIVISION. 
Pi. PERFORM UNTIL EXIT 
DISPLAY "Enter a digit (0 Quits): " 
WITH NO ADVANCING 
ACCEPT Test-Digit 
IF Test-Digit = 0 
EXIT PERFORM 
END-IF 
EVALUATE Digit-Is-Odd ALSO Digit-Is-Prime 
WHEN TRUE ALSO FALSE 
DISPLAY Test-Digit " is ODD" 
WITH NO ADVANCING 
WHEN TRUE ALSO TRUE 
DISPLAY Test-Digit " is PRIME" 
WITH NO ADVANCING 
WHEN FALSE ALSO ANY 
DISPLAY Test-Digit " is EVEN" 
WITH NO ADVANCING 
END-EVALUATE 
EVALUATE Test-Digit 


WHEN < 5 

DISPLAY " and it’s small too" 
WHEN < 8 

DISPLAY " and it’s medium too" 
WHEN OTHER 


DISPLAY " and it’s large too" 
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END-EVALUATE 
END-PERFORM 
DISPLAY "Bye!" 
STOP RUN 


Console output when run (user input follows the colons on the prompts for input): 
Enter a digit (0 Quits): 1 
1 is PRIME and it’s small too 
Enter a digit (0 Quits): 2 
2 is EVEN and it’s small too 
Enter a digit (0 Quits): 3 
3 is PRIME and it’s small too 
Enter a digit (0 Quits): 4 
4 is EVEN and it’s small too 
Enter a digit (0 Quits): 5 
5 is PRIME and it’s medium too 
Enter a digit (0 Quits): 6 
6 is EVEN and it’s medium too 
Enter a digit (0 Quits): 7 
7 is PRIME and it’s medium too 
Enter a digit (0 Quits): 8 
8 is EVEN and it’s large too 
Enter a digit (0 Quits): 9 
9 is ODD and it’s large too 
Enter a digit (0 Quits): 0 
Bye! 
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7.8.15B. EXAMINE 


EXAMINE Syntax j 


EXAMINE { identifier } TALLYING 


{ ALL|LEADING|UNTIL FIRST } literal-1 REPLACING BY literal-2 


literal-3 BY literal-4 


The EXAMINE statement is the pre runner for INSPECT which should be used over the pre 
1970 Cobol standard EXAMINE, and it is used to count the number of times a specified 
character appears in a data item and/or to replace a character with another character. 

1. This statement is only available subject to specific dialects being set when running the 
GnuCOBOL compiler. 

2. In all cases, the description of identifier must be such that its usage is display (explicitly 
or implicitly). 

3. When identifier represents a non numeric data item, examination starts at the leftmost 
character and proceeds to the right. Each character in the data item is examined 
in turn. For purposes of the EXAMINE statement, external floating point items are 
treated as non numeric data items. 

4. When identifier represents a numeric data item, this data item must consist of numeric 
characters, and may possess an operational sign. Examination starts at the leftmost 
character and proceeds to the right. Each character is examined in turn. 

5. If the letter ’S’ is used in the PICTURE of the data item description to indicate the 
presence of an operational sign, the sign is ignored by the EXAMINE statement. 

6. Each literal must consist of a single character belonging to a class consistent with that 
of the identifier; in addition, each literal may be any figurative constant except ALL. If 
identifier is numeric, each literal must be an unsigned integer or the figurative constant 
ZERO (ZEROES, ZEROS). 

7. When Format 1 is used, an integral count is created which replaces the value of a 
special register called TALLY, whose implicit description is that of an unsigned integer 
of five digits. 

8. When the ALL option is used, this count represents the number of occurrences of 
literal-1. 

9. When the LEADING option is used, this count represents the number of occurrences 
of literal-1 prior to encountering a character other than literal-1. 

10. When the UNTIL FIRST option is used, this count represents all characters encoun- 
tered before the first occurrence of literal-1. 
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11. 


12. 
13. 


14. 


Whether Format 2 is used, or the REPLACING option of Format 1, the replacement 
rules are the same. They are as follows: 
When the ALL option is used, literal-2 is substituted for each occurrence of literal-1. 


When the LEADING option is used, the substitution of literal-2 for each occurrence 
of literal-1 terminates as soon as a character other than literal-1 or the right hand 
boundary of the data item is encountered. 

When the UNTIL FIRST option is used, the substitution of literal-2 terminates as soon 
as literal-1 or the right hand boundary of the data item is encountered. 
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7.8.16. EXHIBIT 


EXHIBIT Syntax ] 


EXHIBIT [CHANGED] [NAMED] [position-spec] [ERASE] {identifier-1 | literal-1} ... 


[UPON mnemonic-name-1] 


where position-spec is 
{(position-spec-num, position-spec-num) } 
{(, position-spec-num) } 
{(position-spec-num, ) } 


where position-spec-num is 


{identifier-2} [{+} integer-2] 
{integer-1 } [{-} ] 


The EXHIBIT statement causes an (optionally conditional) display of the literals, and/or 
identifiers (optionally preceded by the identifier name) specified in the statement for the 
purposes of debugging. 

1. EXHIBIT is only present to ease migrations, this is an archaic language element in 
GnuCOBOL (but without the archaic message warning because there is no explicit 
dialect configuration for that other than the reserved word). Depending on the -std 
used it will either compile or not. As the standard says about archaic language elements: 
it should not be used in new compilation groups because better programming practices 
exist 
The use of DISPLAY is more portable and allows for the same feature-set (with the 
exception of CHANGED which GnuCOBOL may not support for a long time and with 
the need of a literal for NAMED). This statement can be removed from any later 
version. 

2. The reserved words NAMED, CHANGED are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 

3. Each identifier specified in the EXHIBIT statement can be any class of data. TALLY 
and RETURN-CODE are the only special registers that can be used as identifiers. 

4. Literals and identifiers displayed by the EXHIBIT statement are separated by a space 
on the displayed line. 

5. Each literal can be any figurative constant other than ALL. 

6. If the literal is numeric, it must be an unsigned integer. 


7. Each execution of an EXHIBIT NAMED statement displays each identifier or literal 
specified, with each identifier (including any qualifiers and subscripts) followed by a 
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10. 


11. 


12. 


13. 
14. 


"=" (equal sign) and its current value. They all appear on a single line on the order 
in which they appear in the statement. 


Each execution of an EXHIBIT CHANGED NAMED statement displays each identifier 
or literal specified, with each identifier (including any qualifiers and subscripts) followed 
by a "=" (equal sign) and its current value. They all appear on a single line on the 
order in which they appear in the statement. However, the display for each identifier 
(name and value) is conditional on the value of that identifier having changed since 
the last execution of the current EXHIBIT statement. If one or more of the identifier 
values have not changed, neither the name nor the value is printed for those identifiers. 
If none of the identifier values has changed, and no literals are specified, no display 
takes place (display of a blank line is suppressed). 


Each execution of an EXHIBIT CHANGED statement displays the current value of 
each identifier or literal specified. They all appear on a single line on the order in 
which they appear in the statement. However, the value display for each identifier is 
conditional on the value of that identifier having changed since the last execution of the 
current EXHIBIT statement. If one or more of the identifier values have not changed, 
the value for those identifiers are not printed and spaces are inserted instead. If none of 
the identifier values has changed, and no literals are specified, a blank line is displayed 
(display of a blank line is not suppressed). 


Each execution of an EXHIBIT statement with neither the CHANGED nor the 
NAMED option displays each identifier or literal specified. They all appear on a 
single line in the order in which they appear in the statement. 


An EXHIBIT statement is the same as an EXHIBIT NAMED statement. 


ERASE is a display attribute which got into GnuCOBOL when MS-COBOL support 
was increased, it is not yet implemented. 


The CHANGED clause is not yet implemented but recognised by GnuCOBOL. 


The UPON mnemonic-name-1 clause is not yet implemented but recognised by Gnu- 
COBOL. 
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7.8.17. EXIT 


EXIT Syntax 


EXIT [ { PROGRAM } [ { RETURNING } ] { identifier-1 } ] 
aii [ { GIVING } ] { literal-1 +] 

{ FUNCTION +] 

, eae Aaa tel 

{ PERFORM [ CYCLE ] } ] 

sais eases Pol 

{ SECTION +] 

, aa Saas sam 

{ PARAGRAPH +] 


The EXIT statement is a multi-purpose statement; it may provide a common end point for 
a series of procedures, exit an in-line PERFORM, paragraph or section or it may mark the 
logical end of a subprogram, returning control back to the calling program. 


1. The EXIT PROGRAM statement is not legal anywhere within a user-defined function. 
2. The EXIT FUNCTION statement cannot be used anywhere within a subroutine. 


3. Neither EXIT PROGRAM nor EXIT FUNCTION may be used within a USE GLOBAL routine 
in DECLARATIVES (see [DECLARATIVES], page 254). 


4. The following points describe the EXIT statement with none of the optional clauses: 


A. When this form of an EXIT statement is used, it must be the only statement in 
the procedure (paragraph or section) in which it occurs. This is not enforced in 
GnuCOBOL. 


B. This usage of the EXIT statement simply provides a common “GO TO” end point 
for a series of procedures, as may be seen in the following example: 


O01 Switches. 
05 Input-File-Switch PIC X(1). 
88 EOF-On-Input-File VALUE ‘‘Y’’ FALSE ‘‘N’’. 


SET EOF-On-Input-File TO FALSE. 
PERFORM 100-Process-A-Transaction THRU 199-Exit 
UNTIL EOF-On-Input-File. 


100-Process-A-Transaction. 
READ Input-File AT END 
SET EOF-On-Input-File TO TRUE 
GO TO 199-Exit 
END-READ. 
IF Input-Rec of Input-File = SPACES 
GO TO 199-Exit *> IGNORE BLANK RECORDS! 
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END-IF. 

<<process the record just read>> 
199-Exit. 

EXIT. 

C. In this case, the EXIT statement takes no other run-time action. 

5. The following points apply to the EXIT PARAGRAPH and EXIT SECTION statements: 

A. Ifan EXIT PARAGRAPH statement or EXIT SECTION statement resides in a paragraph 
within the scope of a procedural PERFORM (see [Procedural PERFORM], page 360), 
control will be returned back to the PERFORM for evaluation of any TIMES, VARYING 
and/or UNTIL clauses. 

B. If an EXIT PARAGRAPH statement or EXIT SECTION statement resides outside the 
scope of a procedural PERFORM, control simply transfers to the first executable 
statement in the next paragraph (EXIT PARAGRAPH) or section (EXIT SECTION). 

C. The following shows how the previous example could have been coded without a 
GO TO by utilizing an EXIT PARAGRAPH statement. 

O01 Switches. 
05 Input-File-Switch PIC X(1). 
88 EOF-On-Input-File VALUE ‘‘Y’’ FALSE ‘‘N’?. 


SET EOF-On-Input-File TO FALSE. 
PERFORM 100-Process-A-Transaction 
UNTIL EOF-On-Input-File. 


100-Process-A-Transaction. 

READ Input-File AT END 
SET EOF-On-Input-File TO TRUE 
EXIT PARAGRAPH 

END-READ. 

IF Input-Rec of Input-File = SPACES 
EXIT PARAGRAPH *> IGNORE BLANK RECORDS! 

END-IF. 

<<process the record just read>> 

6. The following points apply to the EXIT PERFORM and EXIT PERFORM CYCLE statements: 

A. The EXIT PERFORM and EXIT PERFORM CYCLE statements are intended to be used in 
conjunction with an in-line PERFORM statement (see [Inline PERFORM], page 362). 

B. An EXIT PERFORM CYCLE statement will terminate the current iteration of the in- 
line PERFORM, giving control to any TIMES, VARYING and/or UNTIL clauses for them 
to determine if another cycle needs to be performed. 

C. An EXIT PERFORM statement will terminate the in-line PERFORM outright, trans- 
ferring control to the first statement following the END-PERFORM (if there is one) 
or to the next sentence following the PERFORM if there is no END-PERFORM. 

D. This last example shows the final modification to the previous examples by using 
an in-line PERFORM along with EXIT PERFORM and EXIT PERFORM CYCLE statements: 


PERFORM FOREVER 
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READ Input-File AT END 
EXIT PERFORM 
END-READ 
IF Input-Rec of Input-File = SPACES 
EXIT PERFORM CYCLE *> IGNORE BLANK RECORDS! 
END-IF 
<<process the record just read>> 
END PERFORM 


7. The following points apply to the EXIT PROGRAM and EXIT FUNCTION statements: 


A. 


The EXIT PROGRAM and EXIT FUNCTION statements terminate the execution of a 
subroutine (i.e. a program that has been CALLed by another) or user-defined 
function, respectively, returning control back to the calling program. 

An EXIT PROGRAM statement returns control back to the statement following the 
CALL (see [CALL], page 293) of the subprogram. An EXIT FUNCTION statement 
returns control back to the processing of the statement in the calling program that 
invoked the user-defined function. 

For EXIT PROGRAM statement usage of RETURNING statement or GIVING statement 
will provide value defined by indentifer-1 or literal-1 back to the calling routine. 


. If executed by a main program, neither the EXIT PROGRAM nor EXIT FUNCTION 


statements will take any action. 

The COBOL2002 standard has made a common extension to the COBOL lan- 
guage — the GOBACK statement (see [GOBACK], page 334) — a standard language 
element; the GOBACK statement should be strongly considered as the preferred al- 
ternative to both EXIT PROGRAM and EXIT FUNCTION for new subprograms. 
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7.8.18. FREE 


FREE Syntax ] 


FREE { [ ADDRESS OF ] identifier-1 }... 


The FREE statement releases memory previously allocated to the program by the ALLOCATE 
statement (see [ALLOCATE], page 290). 


1. The ADDRESS OF clause is optional and may be omitted. The presence or absence of 
this clause has no effect upon the program. 


2. identifier-1 must have a USAGE (see [USAGE], page 232) of POINTER, or it must be an 
01-level data item with the BASED (see [BASED], page 160) attribute. 


3. If identifier-1 is a USAGE POINTER data item and it contains a valid address, the FREE 
statement will release the memory block the pointer references. In addition, any BASED 
data items that the pointer was used to provide an address for will become un-based 
and therefore unusable. If identifier-1 did not contain a valid address, no action will 
be taken. 

4. If identifier-1 is a BASED data item and that data item is currently based (meaning 
it currently has memory allocated to it), its memory is released and identifier-1 will 
become un-based and therefore unusable. If identifier-1 was not based, no action will 
be taken. 
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7.8.19. GENERATE 


GENERATE Syntax 


GENERATE { report-name-1 } 


{ identifier-1 } 


The GENERATE statement presents data to a report. 
1. The following points apply when identifier-1 is specified: 


A. 


B. 
C. 


identifier-1 must be the name of a DETAIL (see [RWCS Lexicon], page 601) report 
group. 

If necessary, identifier-1 may be qualified with a report name. 

The file in whose FD a REPORT clause exists for the report in which identifier-1 is 


a detail group must be opened for OUTPUT or EXTEND at the time the GENERATE is 
executed. See [OPEN], page 358, for information on file open modes. 


. The report in which identifier-1 is a DETAIL group must have been successfully 


initiated via the INITIATE statement (see [INITIATE], page 343) and not yet 
terminated via the TERMINATE statement (see [TERMINATE], page 410) at the 
time the GENERATE is executed. 


If at least one GENERATE statement of this form is executed against a report, the 
report is said to be a detail report. If no GENERATE statements of this form are 
executed against a report, the report is said to be a summary report. 


2. The following points apply when report-name-1 is specified: 


A. 


B. 


C. 


report-name-1 must be the name of a report having an RD defined for it in the 
report section. 


There must be at least one CONTROL (see [RWCS Lexicon], page 601) group defined 
for report-name-1. 


There cannot be more than one DETAIL group defined for report-name-1. 


The file in whose FD a REPORT report-name-1 clause exists must be open for 
OUTPUT or EXTEND at the time the GENERATE is executed. 

report-name-1 must have been successfully initiated (via INITIATE report-name- 
1) and not yet terminated (via TERMINATE) at the time the GENERATE is exe- 
cuted. See [OPEN], page 358, for information on file open modes. 


. The DETAIL group which is defined for report-name-1 will be processed but will 


not actually be presented to any report page. This will allow summary processing 
to take place. If all GENERATE statements are of this form, the report is said to 
be a summary report. If at least one GENERATE identifier-1 is executed, the 
report is considered to be a detail report. 


3. When the first GENERATE statement for a report is executed, the contents of all control 
fields are saved so they may be referenced during the processing of subsequent GENERATE 
statements. 
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4. When, during the processing of a subsequent GENERATE, it is determined that a control 
field has changed value (ie. a control break has occurred), the appropriate control 
footing and control heading processing will take place and a snapshot of the current 
values of all control fields will again be saved. 
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7.8.20. GOBACK 


GOBACK Syntax ] 


GOBACK [ { RETURNINGIGIVING { literal-1 re i 
ae Aa Op ee a ne A eta Leif 


The GOBACK statement is used to logically terminate an executing program. 

1. If executed within a subprogram (i.e. a subroutine or user-defined function), GOBACK 
behaves like an EXIT PROGRAM or EXIT FUNCTION statement, respectively. 

2. If executed within a main program, GOBACK will act as a STOP RUN statement. 

3. The optional RETURNING clause provides the opportunity to return a numeric value to 
the operating system (technically, an exit status The manner in which the exit status 
value is interrogated by the operating system varies. Windows can use ,ERRORLEVEL% 
to query the exit status while Unix shells such as sh, bash and ksh can query the exit 
status as $7. Other Unix shells may have different ways to access the exit status. 
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7.8.21. GO TO 


7.8.21.1. Simple GO TO 


Simple GO TO Syntax } 


GO TO procedure-name-1 


GO TO ENTRY literal-3 


This form of the GO TO statement unconditionally transfers control in a program to the first 
executable statement within the specified procedure-name-1. 

1. The reserved word TO is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 

2. If this format of the GO TO statement appears in a consecutive sequence of imperative 
statements (see [Imperative Statement], page 718) within a sentence, it must be the 
final statement in the sentence. 

3. If a GO TO is executed within the scope of... 

A. ...an in-line PERFORM (see [PERFORM], page 360), the PERFORM is terminated as 
control of execution transfers to procedure-name-1. 

B. ...a procedural PERFORM (see [PERFORM], page 360), and procedure-name-1 lies 
outside the scope of that PERFORM, the PERFORM is terminated as control of execu- 
tion transfers to procedure-name-1. 

C. ...a MERGE statement (see [MERGE], page 349) OUTPUT PROCEDURE or within the 
scope of either an INPUT PROCEDURE or OUTPUT PROCEDURE of a SORT statement 
(see [File-Based SORT], page 391), and procedure-name-1 lies outside the scope of 
that procedure, the SORT or MERGE operation is terminated as control of execution 
transfers to procedure-name-1. Any sorted or merged data accumulated to that 
point is lost. 

4. A GO TO ENTRY is an GnuCOBOL special purpose extension for use with various Gnu- 
Cobol tools and is not part of any current ISO standard. See also ENTRY. 


5. The GO TO ENTRY format has to be used together with ENTRY FOR GO TO. 
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7.8.21.2. GO TO DEPENDING ON 


GO TO DEPENDING ON Syntax } 


GO 


TO {procedure-name-1} ... 


DEPENDING ON identifier-1 


This form of the GO TO statement will transfer control to any one of a number of specified 
procedure names depending on the numeric value of the identifier specified on the statement. 


1. 


5. 


The reserved word TO is optional and may be omitted. The presence or absence of this 
word has no effect upon the program but does help with read-ability. 


The PICTURE (see [PICTURE], page 194) and/or USAGE (see [USAGE], page 232) of 
the specified identifier-1 must be such as to define it as a numeric, unedited, preferably 
unsigned integer data item. 


If the value of identifier-1 has the value 1, control will be transferred to the 1** specified 
procedure name. If the value is 2, control will transfer to the 2nd procedure name, and 
so on. 


The GO TO ENTRY ... DEPENDING ON format has to be used together with ENTRY FOR GO 
TO. 


If control of execution is transferred to a procedure named on the statement, and the 
GO TO is executed within the scope of... 


A. ...an in-line PERFORM (see [PERFORM], page 360), the PERFORM is terminated as 
control of execution transfers to the procedure named on the statement. 


B. ...a procedural PERFORM (see [PERFORM], page 360), and procedure-name-1 lies 
outside the scope of that PERFORM, the PERFORM is terminated as control of execu- 
tion transfers to the procedure named on the statement. 


C. ...a MERGE statement (see [MERGE], page 349) OUTPUT PROCEDURE or within the 
scope of either an INPUT PROCEDURE or OUTPUT PROCEDURE of a SORT statement 
(see [File-Based SORT], page 391), and procedure-name-1 lies outside the scope of 
that procedure, the SORT or MERGE operation is terminated as control of execution 
transfers to the procedure named on the statement. Any sorted or merged data 
accumulated to that point is lost. 


If the value of identifier-1 is less than 1 or exceeds the total number of procedure names 
specified on the statement, control will simply fall through into the next statement 
following the GO TO. 
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6. The following example shows how GO TO ... DEPENDING ON may be used in a real 
application situation, and compares it against an alternative —- EVALUATE (see 


[EVALUATE], page 320). 


GO TO DEPENDING ON 
GO TO 
ACCT-TYPE-1 
ACCT-TYPE-2 
ACCT-TYPE-3 
DEPENDING ON Acct-Type. 
<<< Invalid Acct Type >>> 
GO TO All-Done. 
Acct-Type-1. 
<<< Handle Acct Type 1 >>> 
GO TO All-Done. 
Acct-Type-2. 
<<< Handle Acct Type 2 >>> 
GO TO All-Done. 
Acct-Type-3. 
<<< Handle Acct Type 3 >>> 
All-Done. 


EVALUATE 
EVALUATE Acct-Type 
WHEN 1 

<<< Handle Acct Type 1 >>> 
WHEN 2 

<<< Handle Acct Type 2 >>> 
WHEN 3 

<<< Handle Acct Type 3 >>> 
WHEN OTHER 

<<< Invalid Acct Type >>> 
END-EVALUATE. 


7. Current programming philosophy would prefer the use of the EVALUATE statement to 


that of this form of the GO TO statement. 


15 January 2023 


Chapter 7 - PROCEDURE DIVISION 


338 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


7.8.22. IF 


IF Syntax } 


ra 


IF conditional-expression 

THEN { imperative-statement-1 } 
{ NEXT SENTENCE t 

ELSE { imperative-statement-2 } ] 

~~~~ { NEXT SENTENCE t 


The IF statement is used to conditionally execute an imperative statement (see [Imperative 
Statement], page 718) or to select one of two different imperative statements to execute 
based upon the TRUE/FALSE value of a conditional expression. 


1. 


The reserved word THEN is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. 


You cannot use both NEXT SENTENCE and the END-IF scope terminator in the same IF 
statement. 

If conditional-expression evaluates to TRUE, imperative-statement-1 will be executed 
regardless of whether or not an ELSE clause is present. Once imperative-statement-1 
has been executed, control falls into the first statement following the END-IF or to the 
first statement of the next sentence if there is no END-IF clause. 

If the optional ELSE clause is present and conditional-expression evaluates to false, then 
(and only then) imperative-statement-2 will be executed. Once imperative-statement- 
2 has been executed, control falls into the first statement following the END-IF or to 
the first statement of the next sentence if there is no END-IF clause. 


The clause NEXT SENTENCE may be substituted for either imperative-statement, but 
not both. If control reaches a NEXT SENTENCE clause due to the truth or falsehood of 
conditional-expression, control will be transferred to the first statement of the next 
sentence found in the program (the first statement after the next period). 


NEXT SENTENCE was needed for COBOL programs that were coded according to 
pre-1985 standards that wish to nest one IF statement inside another. See [Use of 
VERB/END-VERB Constructs], page 55, for an explanation of why NEXT SENTENCE 
was necessary. 

Programs coded for 1985 (and beyond) standards don’t need it, instead using the 
explicit scope-terminator END-IF to inform the compiler where imperative-statement-2 
(or imperative-statement-1 if there is no ELSE clause coded) ends. New GnuCOBOL 
programs should be coded to use the END-IF scope terminator for IF statements. See 
[Use of VERB/END-VERB Constructs], page 55, for additional information. 
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7.8.23. INITIALIZE 


INITIALIZE Syntax 


INITIALIZE|INITIALISE identifier-1... 


[ { category-name-1 } TO VALUE ] 
{ ALL rs 


[ THEN REPLACING { category-name-2 DATA BY 
[ LENGTH OF ] { literal-1 oe emer 
et aw { identifier-1 } 


[ THEN TO DEFAULT ] 


The INITIALIZE statement initializes each identifier-1 with certain specific values, depend- 
ing upon the options specified. 
1. The reserved words DATA, OF, THEN, TO and WITH are optional and may be omitted. 
The presence or absence of these words has no effect upon the program. 
2. The reserved words INITIALIZE and INITIALISE are interchangeable. 
3. The WITH FILLER, REPLACING and DEFAULT clauses are meaningful only if identifier-1 is 


a group item. They are accepted if it’s an elementary item, but will serve no purpose. 
The VALUE clause is meaningful in both cases. 


4. A category-name-1 and/or category-name-2 may be any of the following: 


ALPHABETIC 
The PICTURE (see [PICTURE], page 194) of the data item only contains A 
symbols. 


ALPHANUMERIC 
The PICTURE of the data item contains only X or a combination of A and 9 
symbols. 


ALPHANUMERIC-EDITED 
The PICTURE of the data item contains only X or a combination of A and 9 
symbols plus at least one B, 0 (zero) or / symbol. 


NUMERIC 
The data item is one that is described with a picture less USAGE (see 
[USAGE], page 232) or has a PICTURE composed of nothing but P, 9, S$ 
and V symbols. 
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NUMERIC-EDITED 
The PICTURE of the data item contains nothing but the symbol 9 and at 
least one of the editing symbols $, +, -, CR, DB, ., ,, * or Z. 


NATIONAL 
The data item is one containing nothing but the N symbol. 


NATIONAL-EDITED 
The data item contains nothing but N, B, / and 0 symbols. 


From the sequence of identifier-1 data items specified on the INITIALIZE statement, a 

list of initialized fields referred to as the field list in the remainder of this section, will 

include: 

A. Every identifier-1 that is an elementary item, including any that may have the 
REDEFINES (see [REDEFINES], page 204) clause in their descriptions. 


B. Every non-FILLER elementary item subordinate to identifier-1, provided that ele- 
mentary item neither contains a REDEFINES clause in its definition nor belongs to 
a group item subordinate to identifier-1 which contains a REDEFINES clause in its 
definition. 

C. Ifthe optional WITH FILLER clause is included on the INITIALIZE statement, then 
every FILLER elementary item subordinate to each identifier-1 will be included 
as well, provided that elementary item neither contains a REDEFINES clause in its 
definition nor belongs to a group item subordinate to identifier-1 which contains a 
REDEFINES clause in its definition.. 

Once a field list has been determined, each item in that field list will be initialized as 

if an individual MOVE (see [MOVE], page 352) statement to that effect had been coded. 
The rules for initialization are as follows: 

If no VALUE, REPLACING or DEFAULT clauses are coded, each member of the field list 
will be initialized as if the figurative constant ZERO (if the field list item is numeric or 
numeric-edited) or SPACES (otherwise) were being moved to it. 

If a VALUE clause is specified on the INITIALIZE statement, each qualifying member 
of the field list having a compile-time VALUE (see [VALUE], page 244) specified in its 
definition will be initialized to that value. Field list members with VALUE clauses will 
qualify for this treatment as follows: 

A. Ifthe ALL keyword was specified on the VALUE clause, all members of the field list 
with VALUE clauses will qualify. 

B. If category-name-1 is specified instead of ALL, only those members of the field list 
with VALUE clauses that also meet the criteria set down for the specified category- 
name (see the list above) will qualify. 

C. If you need to apply VALUE initialization to multiple category-name-1 values, you 
will need to use multiple INITIALIZE statements. 

If a REPLACING clause is specified on the INITIALIZE statement, each qualifying member 
of the field list that was not already initialized by a VALUE clause, if any, will be 
initialized to the specified literal-1 or identifier-1 value. 
Only those as-yet uninitialized list members meeting the criteria set forth for the spec- 
ified category-name-2 will qualify for this initialization. 
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If you need to apply REPLACING initialization to multiple category-name-2 values, you 


may repeat the syntax after the reserved word REPLACING, as necessary. 


10. If a DEFAULT clause is specified, any remaining uninitialized members of the field list 
will be initialized according to the default for their class (numeric and numeric-edited 


are initialized to ZERO, all others are initialized to SPACES). 


11. The following example may help your understanding of how the INITIALIZE statement 
works. The sample code makes use of the COBDUMP program to dump the storage 
that is (or is not) being initialized. See Section “COBDUMP” in GnuCOBOL Sample 


Programs, for a source and cross-reference listing of the COBDUMP program. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DemoInitialize. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


O1 Item-1. 
05 Ii-A VALUE ALL ’*?’. 
10 FILLER PIC X(1). 
10 I1-A-1 PIC 9(1) VALUE 9. 
05 I1-B USAGE BINARY-CHAR. 
05 I1-C PIC A(1) VALUE ’C’. 
05 I1i-D PIC X/X VALUE ’ZZ?’. 
05 I1-E OCCURS 2 TIMES PIC 9. 


PROCEDURE DIVISION. 
000-Main. 
DISPLAY "MOVE HIGH-VALUES TO Item-i" 


PERFORM 100-Init-Item-1 
CALL "COBDUMP" USING Item-1 
DISPLAY " " 


DISPLAY "INITIALIZE Item-1" 


INITIALIZE Item-1 

CALL "COBDUMP" USING Item-1 
PERFORM 100-Init-Item-1 
DISPLAY " " 


DISPLAY "INITIALIZE Item-1 WITH FILLER" 


MOVE HIGH-VALUES TO Item-1 
INITIALIZE Item-1 WITH FILLER 
CALL "COBDUMP" USING Item-1 
PERFORM 100-Init-Item-1 
DISPLAY " " 


DISPLAY "INITIALIZE Item-1 ALL TO VALUE" 


15 January 2023 


MOVE HIGH-VALUES TO Item-1 


INITIALIZE Item-1 ALPHANUMERIC TO VALUE 


CALL "COBDUMP" USING Item-1 
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PERFORM 100-Init-Item-1 
DISPLAY " " 


DISPLAY "INITIALIZE Item-1 REPLACING NUMERIC BY 1" 
MOVE HIGH-VALUES TO Item-1 
INITIALIZE Item-1 REPLACING NUMERIC BY 1 
CALL "COBDUMP" USING Item-1 
PERFORM 100-Init-Item-1 
DISPLAY " " 


STOP RUN 


100-Init-Item-1. 
MOVE HIGH-VALUES TO Item-1 


When executed, this program produces the following output: 


MOVE HIGH-VALUES TO Item-1 
<-Addr-> Byte <---------------- Hexadecimal ---------------- > <---- Char ----> 


00404058 1 FF FF FF FF FF FF FF FF FF ue ee eee 


INITIALIZE Item-1 


00404058 1 FF 30 00 20 20 2F 20 30 30 0. / 00 


INITIALIZE Item-1 WITH FILLER 


00404058 1 20 30 00 20 20 2F 20 30 30 0. / 00 


INITIALIZE Item-1 ALL TO VALUE 


00404058 1 2A 2A FF 43 5A 5A 20 FF FF **,CZZ .. 


INITIALIZE Item-1 REPLACING NUMERIC BY 1 
<-Addr-> Byte <---------------- Hexadecimal ---------------- > <---- Char ----> 


00404058 1 FF 31 01 FF FF FF FF 31 31 wil siends 11 
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7.8.24. INITIATE 


INITIATE Syntax 


INITIATE report-name-1 


The INITIATE statement starts Report-Writer Control System (RWCS) processing for a 
report. 


1. Each report-name-1 must be the name of a report having an RD (see [REPORT SEC- 
TION], page 135) defined for it. 


2. The file in whose FD (see [File/Sort-Description], page 124) a REPORT report-name-1 
clause exists must be open for OUTPUT or EXTEND at the time the INITIATE statement 
is executed. See [OPEN], page 358, for more information on file open modes. 


3. The INITIATE statement will initialize all of the following for each report named on 
the statement: 


e All sum counters, if any, will be set to 0 


e The report’s LINE-COUNTER special register (see [Special Registers], page 265) 
will be set to 0 


e The report’s PAGE-COUNTER special register will be set to 1 


4. No report content will actually presented to the report file as a result of a successful 
INITIATE statement — that will not occur until the first GENERATE statement (see 
[GENERATE], page 332) is executed. 
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7.8.25. INSPECT 


INSPECT Syntax 


INSPECT { literal-1 } 
py aan { identifier-1 } 
{ function-reference-1i } 
{ TALLYING { identifier-2 FOR { ALL|LEADING|TRAILING { literal-2 } } 
Reg wee fowww wwwwnwwn wewwnwwn~ F 5 daentifier-3 } } 
{ CHARACTERS } 
[ | { AFTER|BEFORE } INITIAL { literal-3 lee geese. 
Pe ae eee { identifier-4 } | 
{ REPLACING { { { ALL|FIRST|LEADING|TRAILING { literal-4 + } 
HS age OP Oe BE EEE ERE BETA t dentitier=b. ff 
{ CHARACTERS } 
fe } 
BY { [ ALL ] literal-5 } 
peat, eanCaeticd } 
{ identifier-6 } 
[ | { AFTER|BEFORE } INITIAL { literal-6 ed Sean 
). SORA ee ee { identifier-7 } | 
[ CONVERTING { { literal-7 } TO { literal-8 } 
Tawa ar Gf { identifier-8 } ~~ { identifier-9 } 
[ | { AFTER|BEFORE } INITIAL { literal-9 $1] ] 
iy SONOS { identifier-10 } | 


The INSPECT statement is used to perform various counting and/or data-alteration opera- 
tions against strings. 


1. 


The reserved word INITIAL is optional and may be omitted. The presence or absence 
of this words has no effect upon the program. 


Ifa CONVERTING clause is specified, neither the TALLYING nor REPLACING clauses may 
be used. 


If either the TALLYING or REPLACING clauses are specified, the CONVERTING clause cannot 
be used. 


If both the TALLYING and REPLACING clauses are specified, they must be specified in 
the order shown. 
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All literals and identifiers must be explicitly or implicitly defined as alphanumeric or 
alphabetic. 


If function-reference-1 is specified, it must be an invocation of an intrinsic function 
that returns a string result. Additionally, only the TALLYING clause may be specified. 


7. If literal-1 is specified, only the TALLYING clause may be specified. 


10. 


11. 


Whichever is specified — literal-1, identifier-1 or function-reference-1 — that item will 
be referred to in the discussions that follows as the ’inspect subject’. 


The three optional clauses control the operation of this statement as follows: 


A. The CONVERTING clause replaces one or more individual characters found in the 
inspect subject with a different character in much the same manner as is possible 
with the TRANSFORM statement (see [TRANSFORM], page 411). 


B. The REPLACING clause replaces one or more sub strings located in the inspect 
subject with a different, but equally-sized replacement sub string. If you need 
to replace a sub string with another of a different length, consider using ei- 
ther the SUBSTITUTE intrinsic function (see [SUBSTITUTE], page 514) or the 
SUBSTITUTE-CASE intrinsic function (see [SUBSTITUTE-CASE], page 515). 


C. The TALLYING clause counts the number of occurrences of one or more strings of 
characters in the inspect subject. 


The optional INITIAL clauses may be used to limit the range of characters in the inspect 
subject that the CONVERTING, REPLACING or TALLYING instruction in which they occur 
will apply. We call this the ’target range’ of the inspect subject. The target range is 
defined as follows: 


A. Ifthere is no INITIAL clause specified, the target range is the entire inspect subject. 
B. Either a BEFORE phrase, an AFTER phrase or both may be specified. They may be 
specified in any order. 


C. The starting point of the target range will be the first character following the sub 
string identified by the AFTER specification. The ending point will be the last char- 
acter immediately preceding the sub string identified by the BEFORE specification. 

D. If no AFTER is specified, the first character position of the target range will be 
character position #1 of the inspect subject. 


E. If no BEFORE is specified, the last character position of the target range will be the 
last character position of the inspect subject. 
The following points apply to the use of the TALLYING clause: 


A. While there will typically be only be a single set of counting instructions on an 
INSPECT: 


INSPECT Character-String 
TALLYING C-ABC FOR ALL "ABC" 


There could be multiple counting instructions specified: 


INSPECT Character-String 
TALLYING C-ABC FOR ALL "ABC" 
C-BCDE FOR ALL "BCDE" 
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When there are multiple instructions, the one specified first will take priority over 
the one specified second, (and so forth) as the INSPECT proceeds forward through 
the inspect subject, character-by-character. 

With the above example, if the inspect subject were --ABCDEF----BCDEF--, the 
final result of the counting would be that C-ABC would be incremented by 1 while 
C-BCDE would be incremented only once; although the human eye clearly sees two 
‘BCDE’ sequences, the INSPECT ... TALLYING would only “see” the second — the 
first would have been processed by the first (higher-priority) counting instruction. 


B. Each set of counting instructions contains the following information: 


a. A target range, specified by the presence of an AFTER INITIAL and/or BEFORE 
INITIAL clause; the rules for specifying target ranges were covered previously. 


b. A Target Sub string — this is a sequence of characters to be located somewhere 
in the inspect subject and counted. Target sub strings may be defined as 
a literal value (figurative constants are allowed) or by the contents of an 
identifier. If the target sub string is specified as a figurative constant, it will 
be assumed to have a length of one (‘1’) character. The keywords before the 
literal or identifier control how many target sub strings could be identified 
from that replacement instruction, as follows: 


ALL — identifies every possible target sub string that occurs within the target 
range. There are three occurrences of ALL ’XX’ found in aXXabbXXccXXdd. 


LEADING — identifies only an occurrence of the target sub string found either 
at the first character position of the target range or immediately following 
a previously-found occurrence. There are no occurrences of LEADING ’ XX’ 
found in aXXabbXXccXXdd, but there is one occurrence of LEADING ’a’ (the 
first character). 


TRAILING — identifies only an occurrence of the target sub string found either 
at the very end of the target range or toward the end, followed by nothing 
but other occurrences. There are no occurrences of LEADING ’XX’ found in 
aXXabbXXccXXdd, but there are two occurrences of TRAILING ’d’. 


The CHARACTERS option will match any one single character, regardless of 
what that character is. 


. identifier-2 will be incremented by 1 each time the target sub string is found within 


the target range of the inspect subject. The INSPECT statement will not zero-out 
identifier-2 at the start of execution of the INSPECT — it is the programmer’s 
responsibility to ensure that all identifier-2 data items are properly initialized to 
the desired starting values prior to execution of the INSPECT. 


12. The following points apply to the use of the REPLACING clause: 


A. While there will typically be only be a single set of replacement instructions on an 


INSPECT: 


INSPECT Character-String 
REPLACING ALL "ABC" BY "DEF" 


There could be multiple replacement instructions: 
INSPECT Character-String 
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REPLACING ALL "ABC" BY "DEF" 
ALL "BCDE" BY "WXYZ" 


When there are multiple replacement instructions, the one specified first will take 
priority over the one specified second, (and so forth) as the INSPECT proceeds 
forward through the inspect subject, character-by-character. 


With the above example, if the inspect subject were --ABCDEF----BCDEF--, the 
final result of the replacement would be --DEFDEF----WXYZF--. 


B. Each set of replacement instructions contains the following information: 


a. 


b. 


A target range, specified by the presence of an AFTER INITIAL and/or BEFORE 
INITIAL clause; the rules for specifying target ranges were covered previously. 


A Target Sub string — this is a sequence of characters to be located somewhere 
in the inspect subject and subsequently replaced with a new value. Target sub 
strings, which are specified before the BY keyword, may be defined as a literal 
value (figurative constants are allowed) or by the contents of an identifier. If 
the target sub string is specified as a figurative constant, it will be assumed 
to have a length of one (‘1’) character. The keywords before the literal or 
identifier control how many target sub strings could be identified from that 
replacement instruction, as follows: 


ALL — identifies every possible target sub string that occurs within the target 
range. There are three occurrences of ALL ’XX’ found in aXXabbXXccXXdd. 


FIRST — the first occurrence of the target sub string found within the target 
range. The FIRST ’XX’ found in aXXabbXXccXXdd would be the one found 
between the ‘a’ and ‘b’ characters. 


LEADING — an occurrence of the target sub string found either at the 
first character position of the target range or immediately following a 
previously-found occurrence. There are no occurrences of LEADING ’ XX’ 
found in aXXabbXXccXXdd, but there is one occurrence of LEADING ’a’ (the 
first character). 


TRAILING — an occurrence of the target sub string found either at the very 
end of the target range or toward the end, followed by nothing but other occur- 
rences. There are no occurrences of LEADING ’XX’ found in aXXabbXXccXXdd, 
but there are two occurrences of TRAILING ’d’. 


The CHARACTERS option will match any one single character. When you use 
this option, the replacement sub string (see the next item) must be exactly 
one character in length. 


A Replacement Sub string — this is the sequence of characters that should 
replace the target sub string. Replacement sub strings are specified after the 
BY keyword. They too may be specified as a literal, either with or without an 
ALL prefix (again, figurative constants are allowed) or the value of an identifier. 
If a figurative constant is coded, the ALL keyword will be assumed, even if it 
wasn’t specified. Literals without ALL will either be truncated or padded with 
spaces on the right to match the length of the target sub string. Literals with 
ALL or figurative constants will be repeated as necessary to match the length 
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of the target sub string. Identifiers specified as replacement sub strings must 
be defined with a length equal to that of the target sub string. 


13. When both REPLACING and TALLYING are specified: 


A. 


The INSPECT statement will make a single pass through the sequence of charac- 
ters comprising the inspect subject. As the pointer to the current inspect target 
character reaches a point where it falls within the explicit or implicit target ranges 
specified on the operational instructions of the two clauses, the actions specified 
by those instructions will become eligible to be taken. As the character pointer 
reaches a point where it falls past the end of target ranges, the instructions be- 
longing to those target ranges will become disabled. 


. At any point in time, there may well be multipleREPLACING and/or TALLYING op- 


erational instructions active. Only one of the TALLYING and one of the REPLACING 
instructions (if any) can be executed for any one character pointer position. In 
each case, it will be the first of the instructions in each category that produces a 
match with its target string specification. 

When both a TALLYING and a REPLACING instruction have been selected for ex- 
ecution, the TALLYING instruction will be executed first. This guarantees that 
TALLYING will compute occurrences based upon the initial value of the inspect 
subject before any replacements occur. 


14. The following points apply to the use of the CONVERTING clause: 


A. 


A CONVERTING clause performs a series of single-character substitutions against a 
data item in much the same manner as is possible with the TRANSFORM statement 
(see [TRANSFORM], page 411). 

Unlike the TALLYING and REPLACING clauses, both of which may have multiple 
operations specified, there may be only one CONVERTING operation per INSPECT. 


. If the length of literal-7 or identifier-8 (the “from” string) exceeds the length of 


literal-8 or identifier-9 (the “to” string), then the “to” string will be assumed to be 
padded to the right with enough spaces to make it the same length as the “from” 
string. 


. If the length of the “from” string is less than the length of the “to” string, then 


the “to” string will be truncated to the length of the “from” string. 

Each character, in turn, within the “from” string will be searched for in the target 
range of the inspect subject. Each located occurrence will be replaced by the 
corresponding character of the “to” string. 
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7.8.26. MERGE 


MERGE Syntax ] 


MERGE sort-file-1 


{ ON { ASCENDING } KEY identifier-1... }... 
eye aa J 


{ OUTPUT PROCEDURE IS procedure-name-1 } 
Ae. p SL eee eee } 
{ [ THRU|THROUGH procedure-name-2 ] } 
og CA rg } 
{ GIVING file-name-3... } 
5 aaa } 


The DUPLICATES clause is syntactically recognized but is otherwise non-functional. 


The MERGE statement merges the contents of two or more files that have each been 
pre-sorted on a set of specified identical keys. 

1. The reserved words IN, IS, KEY, ON, ORDER, SEQUENCE and WITH are optional and may 
be omitted. The presence or absence of these words has no effect upon the program. 

2. The reserved words THRU and THROUGH are interchangeable. 

3. GnuCOBOL always behaves as if the WITH DUPLICATES IN ORDER clause is specified, 
even if it isn’t. 
While any COBOL implementation’s sort or merge facilities guarantee that records 
with duplicate key values will be in proper sequence with regard to other records 
with different key values, they generally make no promises as to the resulting relative 
sequence of records having duplicate key values with one another. 
Some COBOL implementations provide this optional clause to force their sort and 
merge facilities to retain duplicate key-value records in their original input sequence, 
relative to one another. 

4. The sort-file-1 named on the MERGE statement must be defined using a sort description 
(SD (see [File/Sort-Description], page 124)). This file is referred to in the remainder of 
this discussion as the merge work file. 


5. Each file-name-1, file-name-2 and file-name-3 (if specified) must reference 
ORGANIZATION LINE SEQUENTIAL (see [ORGANIZATION LINE SEQUENTIAL], 
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page 111) or ORGANIZATION SEQUENTIAL (see [ORGANIZATION SEQUENTIAL, 
page 109) files. These files must be defined using a file description (FD (see 
[File/Sort-Description], page 124)). 

The identifier-1 ... field(s) must be defined as field(s) within a record of sort-file-1. 
The record descriptions of file-name-1, file-name-2, file-name-3 (if any) and sort-file-1 
are assumed to be identical in layout and size. While the actual data names used 
for fields in these files’ records may differ, the structure of records, PICTURE (see 
[PICTURE], page 194) of fields, USAGE (see [USAGE], page 232) of fields, size of fields 
and location of fields within the records should match field-by-field across all files, at 
least as far as the KEY fields are concerned. 

A common programming technique when using the MERGE statement is to define the 
records of all files involved as simple elementary items of the form 01 record-name PIC 
X(n). where n is the record size. The only file where records are actually described in 
detail would then be sort-file-1. 

The following rules apply to the files named on the USING clause: 

A. None of them may be open at the time the MERGE is executed. 


B. Each of those files is assumed to be already sorted according to the specifications 
set forth on the MERGE statement’s KEY clause. 

C. No two of those files may be referenced on a SAME RECORD AREA (see [SAME 
RECORD AREA], page 17), SAME SORT AREA or SAME SORT-MERGE AREA state- 
ment. 

The merging process is as follows: 

A. As the MERGE statement begins execution, the first record in each of the USING 
files is read automatically. 

B. As the MERGE statement executes, the current record from each of the USING files is 
examined and compared to each other according to the rules set forth by the KEY 
clause and the alphabet (see [Alphabet-Name-Clause], page 96) specified on the 
COLLATING SEQUENCE clause. The record that should be next in sequence will be 
written to the merge work file and the USING file from which that record came will 
be read so that its next record is available. As end-of-file conditions are reached 
on USING files, those files will be excluded from further processing — processing 
continues with the remaining files until all the contents of all of them have been 
exhausted. 

C. After the merge work file has been populated, the merged data will be written 
to each file-name-3 if the GIVING clause was specified, or will be processed by 
utilizing an OUTPUT PROCEDURE. 

D. When GIVING is specified, none of the file-name-3 files can be open at the time 
the MERGE statement is executed. 

E. When an output procedure is used, the procedure(s) specified on the OUTPUT 
PROCEDURE clause will be invoked as if by a procedural PERFORM (see [Procedural 
PERFORM, page 360) statement with no VARYING, TIMES or UNTIL options spec- 
ified. Merged records may be read from the merge work file — one at a time — 
within the output procedure using the RETURN (see [RETURN], page 373) state- 
ment. 
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A GO TO statement (see [GO TO], page 335) that transfers control out of the output 
procedure will terminate the MERGE statement but allows the program to continue 
executing from the point where the GO TO statement transferred control to. Once an 
output procedure has been “aborted” using a GO TO it cannot be resumed, and the 
contents of the merge work file are lost. You may, however, re-execute the MERGE 
statement itself. Using a GO TO statement to prematurely terminate a merge, or 


re-starting a previously-cancelled merge is not considered good programming style 
and should be avoided. 


An output procedure should be terminated in the same way a procedural PERFORM 
statement would be. Usually, this action will be taken once the RETURN statement 
indicates that all records in the merge work file have been processed, but termi- 
nation could occur at any time — via an EXIT statement (see [EXIT], page 328) 
— if required. 

Neither a file-based SORT statement (see [File-Based SORT], page 391) nor another 
MERGE statement may be executed within the scope of the procedures comprising 


the output procedure unless those statements utilize a different sort or merge work 
file. 


F. Once the output procedure terminates, or the last file-name-3 file has been popu- 
lated with merged data, the output phase — and the MERGE statement itself — is 
complete. 
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7.8.27. MOVE 


7.8.27.1. Simple MOVE 


Simple MOVE Syntax 


MOVE { literal-1 } TO identifier-2... 
~~~~ f identifier-1 } ~~ 


The Simple MOVE statement moves a specific value to one or more receiving data items. 

1. The MOVE statement will replace the contents of one or more receiving data items 
(identifier-2) with a new value — the one specified by literal-1 or identifier-1. 

2. Only numeric data can be moved to a numeric or numeric-edited identifier-2. A MOVE 
involving numeric data will perform any necessary format conversions that might be 
necessary due to differing USAGE (see [USAGE], page 232) specifications. 

3. The contents of the identifier-1 data item will not be changed, unless that same data 
item appears as an identifier-2. Note that such situations will cause a warning message 
to be issued by the compiler, if warning messages are enabled. 
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7.8.27.2. MOVE CORRESPONDING 


MOVE CORRESPONDING Syntax ] 


MOVE CORRESPONDING identifier-1 TO identifier-2... 


The MOVE CORRESPONDING statement similarly-named items from one group item to another. 
1. The reserved word CORRESPONDING may be abbreviated as CORR. 
2. Both identifier-1 and identifier-2 must be group items. 


3. See [CORRESPONDING], page 258, for a discussion of how corresponding matches 
between two group items are established. 


4. When corresponding matches are established, the effect of a MOVE CORRESPONDING on 
those matches will be as if a series of individual MOVEs were done — one for each match. 
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7.8.28. MULTIPLY 


7.8.28.1. MULTIPLY BY 


[ MULTIPLY BY Syntax 


MULTIPLY { literal-1 } BY { identifier-2 
rag acnk ok 0 { identifier-1 } ~~ 


[ ROUNDED [ MODE IS { AWAY-FROM-ZERO Pili dl heres 
pac cus peti 5 Ra Cee ae 
{ NEAREST-AWAY-FROM-ZERO } 
aa cae i SS as } 
{ NEAREST-EVEN 5 
; ARR eS Re ss f 
{ NEAREST-TOWARD-ZERO ie 
ee de te tetera ese + 
{ PROHIBITED as 
pe oi aaa + 
{ TOWARD-GREATER ag 
fe gee gue tye orn en ts 
{ TOWARD-LESSER } 
te ent ier: is 
{ TRUNCATION } 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-MULTIPLY ] 


The MULTIPLY BY statement computes the product of one or more data items (identifier-2) 
and either a numeric literal or another data item. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric un-edited data items; literal-1 must 
be a numeric literal. 


3. The product of identifier-1 or literal-1 and each identifier-2, in turn, will be computed 
and moved to each of the identifier-2 data items, replacing the prior contents. 


4. The value of identifier-1 is not altered, unless that same data item appears as an 
identifier-2. 


5. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 355 


will control how non-integer results will be saved. 

6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERRORI, page 261, for additional information. 
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7.8.28.2. MULTIPLY GIVING 


MULTIPLY GIVING Syntax 


MULTIPLY { literal-1 } BY { literal-2 } GIVING { identifier-3 
a data ara { identifier-1 } ~~ { identifier-2 } ~~~~~~ 


[ ROUNDED [ MODE IS { AWAY-FROM-ZERO beds Sex 
Wigs gts oes Ney tote ogee yng eee } 


An 
z 
zg 
za 
zg 
2g 
2g 
zg 
zg 
z 
zg 
zg 
2g 
2g 
zg 
zg 
zg 
a 
z 
2g 
2g 
zg 
a 

Ww 


A 

zg 

cy 

cy 

zg 

2g 

z 

z 

zg 

2g 

zg 
WEY YY YY YY YY 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-MULTIPLY ] 


The MULTIPLY GIVING statement computes the product of two literals and/or data items 
and saves that result in one or more other data items. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric un-edited data items; literal-1 and 
literal-2 must be numeric literals. 


3. The product of identifier-1 or literal-1 and identifier-2 or literal-2 will be computed 
and moved to each of the identifier-3 data items, replacing their old contents. 


4. Neither the value of identifier-1 nor identifier-2 will be altered, unless either appears 
as an identifier-3. 


5. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 
will control how non-integer results will be saved. 
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6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 
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7.8.29. OPEN 


OPEN Syntax 


OPEN { { INPUT } [ SHARING WITH { ALL OTHER } ] file-name-1 
Oe g = © gh rae ay Sees oat fe. } 
{ OUTPUT } { NO OTHER } 
pane } , aid } 
{ I-0 } { READ ONLY } 
ones 1 NS aii 
{ EXTEND } 
[ { REVERSED Pod) Pay 
teats the } 
{ WITH { NO REWIND } } 
1 Ae Re Le 
{ { LOCK ee} 


The NO REWIND, and REVERSED clauses are syntactically recognized but are otherwise non- 
functional. 


1. 


The OPEN statement makes one or more files described in your program available for use. 


The reserved words OTHER and WITH are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


The SHARING and WITH LOCK clauses may not both be specified in the same OPEN state- 
ment. 


Any file defined in a GnuCOBOL program must be successfully opened before it or any 
of its record descriptions may be referenced on: 


A CLOSE statement (see [CLOSE], page 299) 

A DELETE statement (see [DELETE], page 304) 

A READ statement (see [READ], page 366) 

A REWRITE statement (see [REWRITE], page 374) 
A START statement (see [START], page 397) 

An UNLOCK statement (see [UNLOCK], page 412) 
A WRITE statement (see [WRITE], page 417) 


Any attempt to open a file that is already open will fail with a file status of 41 (see 
[File Status Codes], page 107). 

Any open failure (including status 41) may be trapped using DECLARATIVES 
(see [DECLARATIVES], page 254) or an error procedure established using the 
CBL_ERROR_PROC built-in system subroutine (see [CBL_-ERROR_PROC], page 564) 
built-in subroutine or even just checking the status field defined. It is up to the 
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programmer to check for bad statuses and respond accordingly such as issue a CLOSE 
before dealing with the problem. 


6. The INPUT, OUTPUT, I-O and EXTEND open modes inform GnuCOBOL of the manner 
in which you wish to use the file, as follows: 


INPUT You may only read the existing contents of the file — only the CLOSE, 
READ, START and UNLOCK statements will be allowed. This enforcement 
takes place at execution time, not compilation time. 


OUTPUT You may only write new content (which will completely replace any pre- 
vious file contents) to the file — only the CLOSE, UNLOCK and WRITE state- 
ments will be allowed. This enforcement takes place at execution time, not 
compilation time. 


I-0 You may perform any operation you wish against the file — all file I/O 
statements will be allowed. 


EXTEND You may only write new content (which will be appended after the pre- 
viously existing file contents) to the file — only the CLOSE, UNLOCK and 
WRITE statements will be allowed. This enforcement takes place at execu- 
tion time, not compilation time. You cannot extend an empty file; this will 
not generate a runtime error, but no output will appear in the file. 

7. The SHARING clause informs the GnuCOBOL file runtime modules how you are willing 
to co-exist with any other GnuCOBOL programs that may attempt to open the same 
file after your program does. See [File Sharing], page 57, for an explanation of the 
SHARING clause. 

8. The WITH LOCK option will be functional only if your GnuCOBOL build can support 
it. GnuCOBOL built for MinGW or native Windows will not, because the Unix fcnt1l 
primitive doesn’t exist in those environments. GnuCOBOL built for Cygwin or Unix 
will. 
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7.8.30. PERFORM 


7.8.30.1. Procedural PERFORM 


Procedural PERFORM Syntax ] 


PERFORM procedure-name-1 [ THRU|THROUGH procedure-name-2 ] 


[ { [ WITH TEST { BEFORE } ] { VARYING-Clause +3] 
{ Be gh Beg Ey }  { UNTIL conditional-expression-1 } } 
{ 1 APTER Po Pee } 
Va. lw Ue ep } 
{ UNTIL EXIT|FOREVER } 
Bis, Stkeee ee Pee } 
{ { literal-1 } TIMES } 
{ { identifier-1 } ~~~~~ } 


This format of the PERFORM statement is used to transfer control to one or more procedures, 
which will return control back when complete. Execution of the procedure(s) can be done 
a single time, multiple times, repeatedly until a condition becomes TRUE or forever (with 
some way of breaking out of the control of the PERFORM or of halting program execution 
within the procedure(s)). 


1. 


The reserved word WITH is optional and may be omitted. The presence or absence of 
this word has no effect upon the program. 


2. The reserved words THRU and THROUGH are interchangeable. 
3. The reserved word and phrase FOREVER and UNTIL EXIT are interchangeable. 


4. Both procedure-name-1 and procedure-name-2 must be procedure division sections or 


paragraphs defined in the same program as the PERFORM statement. If procedure-name- 
2 is specified, it must follow procedure-name-1 in the program’s source code. 


The perform scope is defined as being the statements within procedure-name-1, the 


statements within procedure-name-2 and all statements in all procedures defined be- 
tween them. 


literal-1 must be a numeric literal or a reference to a function that returns a numeric 
value. The value must be an integer greater than zero. 


identifier-1 must be an elementary un-edited numeric data item with an integer value 
greater than zero. 


Without the UNTIL, UNTIL EXIT, TIMES, VARYING-Clause (see [VARYING], 
page 363) or FOREVER clauses, the code within the perform scope will be executed 
once, after which control will return to the statement following the PERFORM. 


The FOREVER option will repeatedly execute the code within the perform scope with 
no conditions defined for termination of the repetition — it will be up to the program- 
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10. 


11. 


12. 


13. 


mer to include an EXIT SECTION statement (see [EXIT], page 328) or EXIT PARAGRAPH 
statement within the procedure(s) being performed that will break out of the loop. 


The TIMES option will repeat the execution of the code within the perform scope a fixed 
number of times. When the PERFORM statement begins execution, an internal repeat 
counter (not accessible to the programmer) will be set to the value of literal-1 or the 
value within identifier-1. 


If the counter has a value greater than zero, the statement(s) within the PERFORM scope 
will be executed, after which the counter will be decremented by 1 with each repetition. 
Once that counter reaches zero, repetition will cease and control will fall into the next 
statement following the PERFORM. 


If the identifier-1 option was used, altering the value of that data item within the 
perform scope will not affect the repetition count. 

The UNTIL conditional-expression-1 option will repeat the code within the perform 
scope until the specified conditional expression evaluates to a TRUE value. 


The optional WITH TEST clause will control whether UNTIL testing occurs BEFORE the 
statements within the perform scope are executed on each iteration (creating the possi- 
bility — if conditional-expression-1 is initially TRUE — that the statements within the 
perform scope will never be executed) or AFTER (guaranteeing the statements within 
the perform scope will be executed at least once). 


The default, if this clause is absent, is WITH TEST BEFORE. 

This clause may not be coded when the TIMES clause is used. 

The optional VARYING-Clause is a mechanism that creates an advanced loop- 
management mechanism complete with one or more numeric data items being 


automatically incremented (or decremented) on each loop iteration as well as the 
termination control of an UNTIL clause. See [VARYING], page 363, for the details. 
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7.8.30.2. Inline PERFORM 


( Inline PERFORM Syntax 
PERFORM 
[ { [ WITH TEST { BEFORE } ] { VARYING-Clause Fira 
{ aaa A a } ~=©6. { UNTIL conditional-expression-1 } } 
{ { ARTER- fe } 
nn rr ae } 
{ UNTIL EXIT| FOREVER } 
Ae tee Om ee ae me re as 
{ { literal-1 } TIMES } 
{ { identifier-1 } ~~~~~ } 


imperative-statement-1 


[ END-PERFORM ] 


This format of the PERFORM statement is identical in operation to the procedural 
PERFORM, except for the fact that the statement(s) comprising the perform scope 
(imperative-statement-1) (see [Imperative Statement], page 718) are now specified in-line 
with the PERFORM code rather than in procedures located elsewhere within the program. 
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7.8.30.3. VARYING 


VARYING Syntax 


VARYING identifier-2 FROM { literal-2 


} 


[ BY { literal-3 +] 


a te ~~~ { identifier-3 } ~~ { identifier-4 } 
[ UNTIL conditional-expression-1 ] 
[ AFTER identifier-5 FROM { literal-4 +} [ BY { literal-5 +] 
es ~~~ { identifier-6 } ~~ { identifier-7 } 
[ UNTIL conditional-expression-2 ] ]... 


The VARYING clause, available on both formats of the PERFORM statement, is a looping 
mechanism that allows for the specification of one or more numeric data items that will 
be initialized to a programmer-specified value and automatically incremented by another 
programmer-specified value after each loop iteration. 


1. All identifiers used in a VARYING-Clause must be elementary, un-edited numeric data 


items. All literals must be numeric literals. 


2. The following points describe the sequence of events that take place as a result of the 


VARYING portion of the clause: 


A. When the PERFORM begins execution, the FROM value will be moved to identifier. 
B. Ifthe PERFORM specifies or implies WITH TEST BEFORE, conditional-expression-1 will 


be evaluated and processing of the PERFORM will halt if the expression evaluates 
to TRUE. If WITH TEST BEFORE was not specified or implied, or if the conditional 
expression evaluated to FALSE, processing proceeds with step C. 


. The statements within the perform scope will be executed. If a GO TO executed 


within the perform scope transfers control to a point outside the perform scope, 
processing of the PERFORM will halt. 


. When the statements within the perform scope terminate the loop iteration, by 


one of: 
e allowing the flow of execution to attempt to fall past the last statement in the 
perform scope 
e executing an EXIT PERFORM CYCLE statement (see [EXIT], page 328) 
e executing an EXIT PARAGRAPH statement or EXIT SECTION statement when 
there is only one paragraph (or section) in the perform scope ( this option 
only applies to a procedural PERFORM) 


If WITH TEST AFTER was specified, control will return back to the PERFORM, where 
conditional-expression-1 will be evaluated, and processing of the PERFORM will halt 
if the expression evaluates to TRUE. If WITH TEST AFTER was not specified, or if 
the conditional expression evaluated to FALSE, processing continues with the next 
step. 
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E. The BY value, if any, will be added to identifier-2. If no BY is specified, it will be 
treated as if BY 1 had been specified. 
F. Return to step C. 

3. Most VARYING-Clauses have no AFTER specified. Those that do, however, are estab- 
lishing a loop-within-a-loop situation where the process described above in steps (‘A’) 
through (‘F’) will take place from the AFTER, and those six processing steps actually 
replace step C of the VARYING. This “nesting” process can continue indefinitely, with 
each additional AFTER. 


An example should really help you see this at work. Observe the following code which 
defines a two-dimensional (3 row by 4 column) table and a pair of numeric data items to 
be used to subscript references to each element of the table: 


01 PERFORM-DEMO. 


05 PD-ROW OCCURS 3 TIMES. 
10 PD-COL OCCURS 4 TIMES 
15 PD PIC X(1). 
O01 PD-Col-No PIC 9 COMP. 
O01 PD-Row-No PIC 9 COMP. 
Let’s say the 3x4 “grid” defined by the above structure has these values: 
ABCD 
EFGH 
IJKL 


This code will display ABCDEFGHIJKL on the console output window: 


PERFORM WITH TEST AFTER 
VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 
AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 
DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING 
END-PERFORM 


While this code will display AEIBFJCGKDHL on the console output window: 


PERFORM WITH TEST AFTER 
VARYING PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 
AFTER PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 
DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING 
END-PERFORM 


While we’re looking at sample code, this code displays ABCEFG: 


PERFORM 
VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3 
AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4 
DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING 
END-PERFORM 


By removing the WITH TEST clause, the statement is now assuming WITH TEST BEFORE. 
Since testing now happens before the DISPLAY statement gets executed, when PD-Row-No 
is 3 and PD-Col-No is 4 the DISPLAY statement won’t be executed. 
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Most COBOL programmers, when using WITH TEST BEFORE explicitly or implicitly have 
developed the habit of using ‘>’ rather than ‘=’ on UNTIL clauses. This would make the 
sample code: 

PERFORM 
VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No > 3 
AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No > 4 
DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING 
END-PERFORM 


With this change, ABCDEFGHIJKL is once again displayed. 
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7.8.31. READ 


7.8.31.1. Sequential READ 


Sequential READ Syntax 


[ 


READ file-name-1 [ { NEXT|PREVIOUS } ] RECORD [ INTO identifier-1 ] 


Sou ares } as 
[ { IGNORING LOCK +] 
Tanne w yee” os } 
{ WITH [ NO ] LOCK } 
{ Si GEN 
{ WITH KEPT LOCK } 
, a cS } 
{ WITH IGNORE LOCK } 
MI SSC LALs } 
{ WITH WAIT } 


[ AT END imperative-statement-1 ] 


[ NOT AT END imperative-statement-2 ] 


END-READ ] 


This form of the READ statement retrieves the next (or previous) record from a file. 


1. 


The reserved words AT, RECORD and WITH are optional and may be omitted. The 
presence or absence of these words has no effect upon the program. 

The file-name-1 file must have been defined via an FD (see [File/Sort-Description], 
page 124), not an SD. 

The file-name-1 file must currently be open for INPUT (see [File OPEN Modes], 
page 359) or I-0. 

If fileename-1 is an ORGANIZATION RELATIVE (see [ORGANIZATION RELATIVE], 
page 113) or ORGANIZATION INDEXED (see [ORGANIZATION INDEXED], page 115) 
file with an ACCESS MODE RANDOM, this statement cannot be used. 

If file-name-1 was specified as ACCESS MODE SEQUENTIAL, this is the only format of the 
READ statement that is available. 

If fileename-1 is an ORGANIZATION RELATIVE (see [ORGANIZATION RELATIVE], 
page 113) or ORGANIZATION INDEXED (see [ORGANIZATION INDEXED], page 115) 
file with ACCESS MODE DYNAMIC, this statement as well as a random READ (see [Random 
READ], page 368) may be used. 

The keywords NEXT and PREVIOUS specify what “direction of travel” the reading 
process will take through the file. If neither is specified, NEXT is assumed. 
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8. The PREVIOUS option is available only for ORGANIZATION INDEXED files. 


10. 


11. 


12. 


13. 


14. 


15. 


When reading any sequential (any organization) or relative file, the “next” direction 
refers to the physical sequence of records in the file. When reading an indexed file, the 
“next” and “previous” directions refer to the sequence of primary or alternate record 
key values in the file’s records, regardless of where the records physically occur within 
the file. 


The minimal statement READ file-name-1 is perfectly legal according to both READ 
formats. For that reason, when ACCESS MODE DYNAMIC has been specified and you want 
to tell the GnuCOBOL compiler that this minimal statement should be treated as a 
sequential READ, you must add either NEXT or PREVIOUS to the statement (otherwise it 
will be treated as a random READ). 


A successful sequential READ will retrieve the next available record from file-name-1, in 
either a “next” or “previous” direction from the most-recently-read record, depending 
upon the use of the NEXT or PREVIOUS option. The newly-retrieved record data will be 
saved into the 01-level record structure(s) that immediately follow the file’s FD. If the 
optional INTO clause is present, a copy of the just-retrieved record will be automatically 
moved to identifier-1. 


When an ORGANIZATION RELATIVE file has been successfully read, the file’s RELATIVE 
KEY (see [ORGANIZATION RELATIVE], page 113) field will be automatically popu- 


lated with the relative record number (ordinal occurrence number) of the record in the 
file. 

The optional LOCK options may be used to manually control access to the retrieved 
record by other programs while this program is running. See [Record Locking], page 59, 
to review the various record locking behaviours. 

The optional AT END clause, if coded, is used to detect and react to the failure of an 
attempt to retrieve another record from the file due to an end-of-file (i.e. no more 
records) condition. 

The optional NOT AT END clause, if coded, will check for a file status value of 00. See 
[File Status Codes], page 107, for additional information. 
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7.8.31.2. Random READ 


Random READ Syntax 


READ file-name-1 RECORD [ INTO identifier-1 ] 


[ { IGNORING LOCK ¥] 
aa ae ea } 
{ WITH [ NO ] LOCK } 
{ ie See or 
{ WITH KEPT LOCK } 
BJ 0 ates pane } 
{ WITH IGNORE LOCK } 
A See ee } 
{ WITH WAIT Bg 


[ KEY IS identifier-2 ] 


[ INVALID KEY imperative-statement-1 ] 


This form of the READ statement retrieves an arbitrary record from an ORGANIZATION 
RELATIVE (see [ORGANIZATION RELATIVE], page 113) or ORGANIZATION INDEXED (see 
[ORGANIZATION INDEXED], page 115) file. 


1. 


The reserved words IS, KEY (on the INVALID and NOT INVALID clauses), RECORD and 
WITH are optional and may be omitted. The presence or absence of these words has no 
effect upon the program. 

The file-name-1 file must have been defined via an FD (see [File/Sort-Description], 
page 124), not an SD. 

The file-name-1 file must currently be open for INPUT (see [File OPEN Modes], 
page 359) or I-0. 

If the ACCESS MODE of file-name-1 is SEQUENTIAL, or the ORGANIZATION of the file is 
any form of sequential, this format of the READ statement cannot be used. 


If the ACCESS MODE of file-name-1 is RANDOM, this is the only format of the READ state- 
ment that is available. 


If file-name-1 is an ORGANIZATION RELATIVE (see [ORGANIZATION RELATIVE], 
page 113) or ORGANIZATION INDEXED (see [ORGANIZATION INDEXED}, page 115) file 
with ACCESS MODE DYNAMIC, this statement as well as a sequential READ (see [Sequential 
READ], page 366) may be used. 
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t 


10. 


11. 


12. 


The minimal statement READ file-name-1 is perfectly legal according to both READ 
formats. For that reason, when ACCESS MODE DYNAMIC has been specified and you want 
to tell the GnuCOBOL compiler that this minimal statement should be treated as a 
random READ, you must omit the NEXT or PREVIOUS available to the sequential format 
of the READ statement to ensure the statement will be treated as a random READ. 


The optional KEY clause tells the compiler how a record is to be located in the file. 
If the KEY clause is absent, and the file is 


ORGANIZATION RELATIVE 
the contents of the field declared as the file’s RELATIVE KEY will be used to 
identify a record 


ORGANIZATION INDEXED 
the contents of the field declared as the file’s RECORD KEY will be used to 
identify a record. 


If the KEY clause is specified, and the file is 


ORGANIZATION RELATIVE 
the contents of identifier-2 will be used as the relative record number of 
the record to be accessed. identifier-2 need not be the RELATIVE KEY (see 
[ORGANIZATION RELATIVE], page 113) field of the file (although it 
could be if you wish). 


ORGANIZATION INDEXED 
identifier-2 must be the RECORD KEY (see [ORGANIZATION INDEXED], 
page 115) or one of the file’s ALTERNATE RECORD KEY fields (if any). The 
current contents of that field will identify the record to be accessed. If 
an alternate record key is used, and that key allows duplicate values, the 
record accessed will be the first one having that key value. 


Once read from the file, the newly-retrieved record data will be saved into the 01-level 
record structure(s) that immediately follow the file’s FD. If the optional INTO clause is 
present, a copy of the just-retrieved record will be automatically moved to identifier-1. 


When an ORGANIZATION RELATIVE file has been successfully read, the file’s RELATIVE 
KEY (see [ORGANIZATION RELATIVE], page 113) field will be automatically popu- 


lated with the relative record number (ordinal occurrence number) of the record in the 
file. 


The optional LOCK options may be used to manually control access to the retrieved 
record by other programs while this program is running. See [Record Locking], page 59, 
to review the various record locking behaviours. 

The optional INVALID KEY and NOT INVALID KEY clauses may be used to detect and 
react to the failure or success, respectively, by detecting non-zero (typically 23 = key 
not found = record not found) and 00 file status codes, respectively. See [File Status 
Codes], page 107, for additional information. 
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7.8.32. READY TRACE 


READY TRACE Syntax 


READY TRACE 


The READY TRACE statement turns procedure or procedure-and-statement tracing on. 


1. In order for this statement to be functional, tracing code must have been generated 
into the compiled program using either the -ftrace switch (procedures only) or 
-ftraceall switch (procedures and statements). 


2. Tracing may be turned off at any point by executing the RESET TRACE statement (see 
[RESET TRACE], page 372). 


3. The COB_SET_TRACE run-time environment variable (see [Run Time Environment 
Variables], page 654) provides another way to control tracing. If this environment 
variable is set to a value of ‘Y’ prior to the start of program execution, tracing starts 
at the point the program begins execution, as if READY TRACE were the first executed 
statement. 
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7.8.33. RELEASE 


RELEASE Syntax 


RELEASE record-name-1 [ FROM { literal-1 3] 
ae we ks ~~~~ { identifier-1 } 


The RELEASE statement adds a new record to a sort work file. 


1. This statement is valid only within the INPUT PROCEDURE of a file-based SORT statement 
(see [File-Based SORT], page 391). 


2. The specified record-name-1 must be a record defined to the sort description (SD (see 
[File/Sort-Description], page 124)) of the sort work file being processed by the current 
sort. 

3. The optional FROM clause will cause literal-1 or identifier-1 to be automatically moved 
into record-name-1 prior to writing record-name-1’s contents to the file-name-1. If this 
clause is not specified, it is the programmer’s responsibility to populate record-name-1 
with the desired data prior to executing the RELEASE. 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


372 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


7.8.34. RESET TRACE 


RESET TRACE Syntax 


RESET TRACE 


The RESET TRACE statement turns procedure or procedure-and-statement tracing off. 


1. 


By default, procedure and procedure-and-statement tracing is off as programs begin 
execution. The READY TRACE statement (see [READY TRACE], page 370) can be used 
to turn tracing on. 


In order for this statement to be functional, tracing code must have been generated 
into the compiled program using either the -ftrace switch (procedures only) or 
-ftraceall switch (procedures and statements). 


The COB_SET_TRACE run-time environment variable (see [Run Time Environment 
Variables], page 654) provides another way to control tracing. If this environment 
variable is set to a value of ‘Y’ prior to the start of program execution, tracing started 
at the point the program begins execution, as if READY TRACE were the first. executed 
statement. The RESET TRACE statement, if executed, will then turn off tracing. 
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7.8.35. RETURN 


RETURN Syntax ] 


[ 


RETURN sort-file-name-1 RECORD 


{ INTO identifier-1 ] 


AT END imperative-statement-1 


[ NOT AT END imperative-statement-2 ] 


END-RETURN ] 


The RETURN statement reads a record from a sort or merge work file. 


1. 


The reserved words AT and RECORD are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


The RETURN statement is valid only within the OUTPUT PROCEDURE of a file-based SORT 
(see [File-Based SORT], page 391) or a MERGE statement (see [MERGE], page 349) 
statement. 


The sort-file-name-1 file must be a sort- or merge work file defined with a SD (see 
[File/Sort-Description], page 124), not an FD. 

A successful RETURN will retrieve the next available record from sort-file-name-1. The 
newly-retrieved record data will be saved into the 01-level record structure(s) that 
immediately follow the file’s SD. If the optional INTO clause is present, a copy of the 
just-retrieved record will be automatically moved to identifier-1. 

The mandatory AT END clause is used to detect and react to the failure of an attempt 
to retrieve another record from the file due to an end-of-file (i.e. no more records) 
condition. 

The optional NOT AT END clause, if coded, will check checking for a file status value of 
00. See [File Status Codes], page 107, for additional information. 
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7.8.36. REWRITE 


REWRITE Syntax 


REWRITE record-name-1 
[ FROM { literal-1 } ] 
~~~~ £ identifier-1 } 


[ WITH [ NO ] LOCK ] 


[ INVALID KEY imperative-statement-1 ] 


[ NOT INVALID KEY imperative-statement-2 ] 


The REWRITE statement replaces a logical record on a disk file. 


1. 


The reserved words KEY and WITH are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


The record-name-1 specified on the statement must be defined as an 01-level record 
subordinate to the File Description (FD (see [File/Sort-Description], page 124)) of a file 
that is currently open for I-0O (see [File OPEN Modes], page 359). 


The optional FROM clause will cause literal-1 or identifier-1 to be automatically moved 
into record-name-1 prior to writing record-name-1’s contents to the file-name-1. If this 
clause is not specified, it is the programmer’s responsibility to populate record-name-1 
with the desired data prior to executing the REWRITE. 


This statement may not be used with ORGANIZATION LINE SEQUENTIAL (see 
[ORGANIZATION LINE SEQUENTIAL], page 111) files. 


Rewriting a record does not cause the contents of the file to be physically updated 
until the next block of the file is read, a COMMIT (see [COMMIT], page 300) or UNLOCK 
statement (see [UNLOCK], page 412) is issued or that file is closed. 


If the file has ORGANIZATION SEQUENTIAL (see [ORGANIZATION SEQUENTIAL, 

page 109): 

A. The record to be rewritten will be the one retrieved by the most-recently executed 
READ (see [READ], page 366) of the file. 

B. If the FD of the file contains the RECORD CONTAINS or RECORD IS VARYING clause, 
and that clause allows the record size to vary, the size of record-name-1 cannot be 
altered. 


If the file has ORGANIZATION RELATIVE (see [ORGANIZATION RELATIVE], page 113) 
or ORGANIZATION INDEXED (see [ORGANIZATION INDEXED], page 115): 
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A. Ifthe file has ACCESS MODE SEQUENTIAL, the record to be rewritten will be the one 
retrieved by the most-recently executed READ of the file. If the file has ACCESS 
MODE RANDOM or ACCESS MODE DYNAMIC, no READ is required before a record may be 
rewritten — the RELATIVE KEY or RECORD KEY definition for the file, respectively, 
will specify the record to be updated. 

B. If the FD of the file contains the RECORD CONTAINS or RECORD IS VARYING clause, 
and that clause allows the record size to vary, the size can be altered. 

8. The optional LOCK options may be used to manually control access to the re-written 
record by other programs while this program is running. See [Record Locking], page 59, 
to review the various record locking behaviours. 

9. The optional INVALID KEY and NOT INVALID KEY clauses may be used to detect and 
react to the failure or success, respectively, by detecting non-zero (typically 23 = key 
not found = record not found) and 00 file status codes, respectively. See [File Status 
Codes], page 107, for additional information. 
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7.8.37. ROLLBACK 


ROLLBACK Syntax 


ROLLBACK 


The ROLLBACK statement has the same effect as if an UNLOCK statement (see [UNLOCK], 
page 412) were executed against every open file in the program. 


1. All locks currently being held for all open files will be released. 


2. See [Record Locking], page 59, to review the various record locking behaviours. 
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7.8.38. SEARCH 


SEARCH Syntax 


SEARCH table-name-1 


[ AT END imperative-statement-1 ] 


{ WHEN conditional-expression-1 imperative-statement-2 }... 


[ END-SEARCH ] 


The SEARCH statement is used to sequentially search a table, stopping either once a specific 
value is located within the table or when the table has been completely searched. 


1. 


The reserved word AT is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


The searching process will be controlled through a Search Index — a data item witha 
USAGE (see [USAGE], page 232) of INDEX. The search index is either the index-name-1 
identifier specified on the VARYING clause or — if no VARYING is specified — the USAGE 

INDEX data item implicitly created by an INDEXED BY (see [OCCURS], page 190) clause 

in the table’s definition. 

At the time the SEARCH statement is executed, the current value of the search index 
data item will define the starting position in the table where the searching process will 
begin. Typically, one initializes that index to a value of 1 before starting the SEARCH 
via SET search-index TO 1. 

Each of the conditional-expression-ns on the WHEN clause(s) should involve a data ele- 
ment within the table, subscripted using the search index. 

The searching process is as follows: 

A. Each conditional-expression-n will be evaluated, in turn, until either one evaluates 
to a value of TRUE or all have evaluated to FALSE. 

B. The imperative-statement-n (see [Imperative Statement], page 718) specified on 
the WHEN clause whose conditional-expression-n evaluated to TRUE will be executed; 
after that, the search will be considered complete and control will fall into the first 
executable statement following the SEARCH. 

C. If all conditional-expression-ns evaluated to FALSE: 

e The search index will be incremented by 1 

e If the search index now has a value greater than the number of entries in the 
table, the search is considered to have failed and the imperative-statement-1 
on the optional AT END clause, if any, will be executed. After that, control 
will fall into the first executable statement following the SEARCH. 
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e Ifthe search index now has a value less than or equal to the number of entries 
in the table, search processing returns back to step A. 
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7.8.39. SEARCH ALL 


SEARCH ALL Syntax ] 


SEARCH ALL table-name-1 


[ AT END imperative-statement-1 ] 


WHEN conditional-expression-1 imperative-statement-2 


[ END-SEARCH ] 


The SEARCH ALL statement performs a binary, or half-interval, search against a sorted ta- 
ble. This is generally significantly faster than performing a sequential SEARCH of a table, 
especially if the table contains a large number of entries. 


1. The reserved word AT is optional and may be omitted. The presence or absence of this 
word has no effect upon the program. 


2. To be eligible for searching via SEARCH ALL: 
A. The OCCURS clause of table-name-1 must contain the following elements: 


e An INDEXED BY entry to define an implicit search index data item with a 
USAGE (see [USAGE], page 232) of INDEX. 


e An ASCENDING KEY or DESCENDING KEY clause to specify the field within the 
table by which all entries in the table are sorted. 


B. Just because the table has one or more KEY clauses doesn’t mean the data is 
actually in that sequence in the table — the actual sequence of the data must 
agree with the KEY clause(s)! A table-based SORT (see [Table SORT], page 395) 
can prove very useful in this regard. 


C. No two records in the table may have the same KEY field values. If the table 
has multiple KEY definitions, then no two records in the table may have the same 
combination of KEY field values. 


3. If rule A is violated, the compiler will reject the SEARCH ALL. If rules B and/or C' are 
violated, there will be no message issued by the compiler, but the run-time results of a 
SEARCH ALL against the table will probably be incorrect. 


4. The conditional-expression-1 should involve the KEY field(s), using the search index 
(the table’s INDEXED BY index name) as a subscript. 


5. The function of the single, mandatory, WHEN clause is to compare the key field(s) of 
the table, as indexed by the search index data item, against whatever literal and/or 
identifier values you are comparing the key field(s) to in the conditional-expression-1 
in order to locate the desired entry in the table. The search index will be automatically 
varied in a manner designed to require the minimum number of tests. 
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The internal processing of the SEARCH ALL statement begins by setting internal 
“first” and “last” pointers to the 1°* and last entry locations of the table. Processing 
then proceeds as follows: 


A. The entry half-way between “first” and “last” is identified. We’ll call this the 
“current” entry, and will set its table entry location into index-name-1. 


B. The conditional-expression-1 is evaluated. This comparison of the key(s) against 
the target literal/identifier values will have one of three possible outcomes: 


e If the key(s) and value(s) match, imperative-statement-2 (see [Imperative 
Statement], page 718) is executed, after which control falls through into the 
next statement following the SEARCH ALL. 


e Ifthe key(s) are LESS THAN the value(s), then the table entry being searched 
for can only occur in the “current” to “last” range of the table, so a new “first” 
pointer value is set (it will be set to the “current” pointer). 


e If the key(s) are GREATER THAN the value(s), then the table entry being 
searched for can only occur in the “first” to “current” range of the table, so a 
new “last” pointer value is set (it will be set to the “current” pointer). 


C. If the new “first” and “last” pointers are different than the old “first” and “last” 
pointers, there’s more left to be searched, so return to step A and continue. 


D. If the new “first” and “last” pointers are the same as the old “first” and “last” 
pointers, the table has been exhausted and the entry being searched for cannot be 
found; imperative-statement-1 is executed, after which control falls through into 
the next statement following the SEARCH ALL. If there is no AT END clause coded, 
control simply falls into the next statement following the SEARCH ALL. 


The net effect of the above algorithm is that only a fraction of the number of elements 
in the table need ever be tested in order to decide whether or not a particular entry 
exists. This is because the half the remaining entries in the table are discarded each 
time an entry is checked. 


Computer scientists will compare the two techniques implemented by the SEARCH and 
SEARCH ALL statements as follows: 


When searching a table with N entries, a sequential search will need an average of N/2 
tests and a worst case of N tests in order to find an entry and N tests to identify that 
an entry doesn’t exist. 

When searching a table with N entries, a binary search will need a worst-case of log2(N) 


tests in order to find an entry and log2(N) tests to identify that an entry doesn’t exist 
(N = the number of entries in the table), where log2 is the base-2 logarithm function. 


Here’s a more practical view of the difference. Let’s say that a table has 1,000 entries in 
With a sequential search, on average, you’ll have to check 500 of them to find an entry 


and you'll have to look at all 1,000 of them to find that an entry doesn’t exist. 


With a binary search, express the number of entries as a binary number (1,000 = 


1111101000), count the number of digits in the result (which is, essentially, what a log- 
arithm is, when rounded up to the next integer — the number of digits a decimal number 
would have if expressed in the logarithm’s number base). In this case, we end up with 10 
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— that is the worst-case number of tests required to find an entry or to identify that it 
doesn’t exist. That’s quite an improvement! 
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7.8.40. SET 


7.8.40.1. SET ENVIRONMENT 


i SET ENVIRONMENT Syntax 


SET ENVIRONMENT { literal-1 } TO { literal-2 } 
Pap MO a SSR, { identifier-1 } ~~ { identifier-2 } 


The SET ENVIRONMENT statement provides a straight-forward means of setting environment 
values from within a program. 

1. The value of literal-1 or identifier-1 specifies the name of the environment variable to 
set. 

2. The value of literal-2 or identifier-2 specifies the value to be assigned to the environment 
variable. 

3. Environment variables created or changed from within GnuCOBOL programs will be 
available to any sub-shell processes spawned by that program (i.e. CALL "SYSTEM") 
but will not be known to the shell or console window that started the GnuCOBOL 
program. 


This is a much simpler and more readable means of setting environment variables 
than by using the DISPLAY UPON ENVIRONMENT-NAME statement (see [DISPLAY UPON 
ENVIRONMENT-NAME}, page 308). For example, these two code sequences produce 
identical results: 


DISPLAY "VARNAME" UPON ENVIRONMENT-NAME 
DISPLAY "VALUE" UPON ENVIRONMENT-VALUE 


SET ENVIRONMENT "VARNAME" TO "VALUE" 
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7.8.40.2. SET Program-Pointer 


SET Program-Pointer Syntax 


SET program-pointer-1 TO ENTRY { literal-1 } 
pene ON eS { identifier-1 } 


The SET Program-Pointer statement allows you to retrieve the address of a procedure divi- 
sion code module — specifically the PROGRAM-ID, FUNCTION-ID or an entry-point established 
via the ENTRY statement (see [ENTRY], page 318). 

1. The USAGE (see [USAGE], page 232) of program-pointer-1 must be PROGRAM-POINTER. 

2. The literal-1 or identifier-1 value specified must name a primary entry-point name 
(PROGRAM-ID of a subroutine or FUNCTION-ID of a user-defined function) or an alternate 
entry-point defined via an ENTRY statement within a subprogram. 

3. Once the address of a procedure division code area has been acquired in this way, the 
address could be passed to a subroutine (usually written in C) for whatever use it 
needs it for. For examples of PROGRAM-POINTERs at work, see the discussions of the 
CBL_ERROR_PROC built-in system subroutine (see [CBL_ERROR_PROC], page 564) and 
CBL_EXIT_PROC built-in system subroutine (see [CBL_EXIT_PROC], page 566). 
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7.8.40.3. SET ADDRESS 


SET ADDRESS Syntax 


SET [ ADDRESS OF ] { pointer-name-1 }... 
SD ERR a) ey { identifier-1 } 


TO [ ADDRESS OF ] { pointer-name-2 } 
a { identifier-2 } 


The SET ADDRESS statement can be used to work with the addresses of data items rather 
than their contents. 

1. When the ADDRESS OF clause is used before the TO you will be using this statement 
to alter the address of a linkage section or BASED (see [BASED], page 160) data item. 
Without that clause you will be assigning an address to one or more data items whose 
USAGE (see [USAGE], page 232) is POINTER. 

2. When the ADDRESS OF clause is used after the TO, this statement will be identifying 
the address of identifier-2 as the address to be assigned to identifier-1 or stored in 
pointer-name-1. 

3. If the ADDRESS OF clause is absent after the TO, the contents of pointer-name-2 will 
serve as the address to be assigned. 
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7.8.40.4. SET Index 


( SET Index Syntax } 


SET index-name-1 TO { literal-1 } 
css ~~ { identifier-2 } 


This statement assigns a value to a USAGE INDEX data item. 


1. Either the USAGE (see [USAGE], page 232) of index-name-1 should be INDEX, or index- 
name-1 must be identified in a table INDEXED BY clause. 
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7.8.40.5. SET UP/DOWN 


SET UP/DOWN Syntax 


SET identifier-1 { UP  } BY [ LENGTH OF ] { literal-1 } 
ee BN eps Sees eae { identifier-2 } 
{ DOWN } 


Use this statement to increment or decrement the value of an index or pointer by a specified 
amount. 
1. The USAGE (see [USAGE], page 232) of identifier-1 must be INDEX, POINTER or 
PROGRAM-POINTER. 
2. The typical usage when identifier-1 is a USAGE INDEX data item is to increment its value 
UP or DOWN by 1, since an index is usually being used to sequentially walk through the 
elements of a table. 
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7.8.40.6. SET Condition Name 


( SET Condition Name Syntax } 


SET condition-name-1... TO { TRUE } 
mse pay ay ee 
{ FALSE } 


The SET Condition Name statement provides one method of specifying the TRUE / FALSE 
value of a level-88 condition name. 

1. By setting the specified condition-name-1(s) to a TRUE or FALSE value, you will actually 
be assigning a value to the parent data item(s) to which the condition name data item(s) 
is(are) subordinate to. 

2. When specifying TRUE, the value assigned to each parent data item will be the first 
value specified on the condition name’s VALUE clause. 

3. When specifying FALSE, the value assigned to each parent data item will be the value 
specified for the FALSE clause of the condition name’s definition; if any condition-name- 
1 occurrence lacks a FALSE clause, the SET statement will be rejected by the compiler. 
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7.8.40.7. SET Switch 


f SET Switch Syntax 


SET mnemonic-name-1... TO { ON } 
ate Ce ee op 
{ OFF } 


This form of the SET statement is used to turn switches on or off. 
1. Switches are defined using the SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) para- 
graph. 
2. Switches may be tested via the IF statement (see [IF], page 338) and a Switch-Status 
Condition. See [Switch-Status Conditions], page 49, for more information. 
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7.8.40.8. SET ATTRIBUTE 


SET ATTRIBUTE Syntax ] 


SET identifier-1 ATTRIBUTE { { BELL 
wn nw RR RR { ~nwnwe 


A 

2g 

zg 

zg 

a 

zg 

a 

a 

2g 
SY YY YY 


The SET ATTRIBUTE statement may be used to modify one or more attributes of a screen 
section data item at run-time. 

1. When making an attribute change to identifier-1, the change will not become visible on 
the screen until the screen section data item containing identifier-1 is next accepted (if 
identifier-1 is an input field) or is next displayed (if identifier-1 is not an input field). 

2. The attributes shown in the syntax diagram are the only ones that may be altered 
by this statement. See [Data Description Clauses], page 154, for information on their 
usage. 
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7.8.40.9. SET LAST EXCEPTION 


SET ATTRIBUTE Syntax ] 


SET LAST EXCEPTION TO { OFF } 


The SET LAST EXCEPTION statement will set the last program exception status to indicate 
no exception. 

1. The predefined object reference EXCEPTION-OBJECT is set to null, and the last 
exception status is set to indicate no exception. 

2. This action resets the global exception object completely (FUNCTION EXCEPTION- 
{FILE, LOCATION, STATEMENT, STATUS } ), and will not show anything after- 
wards), no matter what the last exception was (such as a divide by zero). Use with 
care. 
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7.8.41. SORT 


7.8.41.1. File-Based SORT 


i File-Based SORT Syntax 


SORT sort-file-1i 


{ ON { ASCENDING } KEY identifier-1... }... 
ae ape He ey } 
{ DESCENDING } 
[ WITH DUPLICATES IN ORDER ] 
[ COLLATING SEQUENCE IS alphabet-name-1 ] 
{ INPUT PROCEDURE IS procedure-name-1 } 
A Pusey tye yety pee ss 
{ [ THRU| THROUGH procedure-name-2 ] } 
Me Og erred yp Ne hepee } 
{ USING file-name-1 } 
{ OUTPUT PROCEDURE IS procedure-name-3 } 
Te Pk et ss 
{ [ THRU|THROUGH procedure-name-4 ] } 
qe ene } 
{ GIVING file-name-2 ... } 


The DUPLICATES clause is syntactically recognized but is otherwise non-functional. 


This format of the SORT statement is designed to sort large volumes of data according 
to one or more key fields. 

1. The reserved words IN, IS, KEY, ON, ORDER, SEQUENCE and WITH are optional and may 
be omitted. The presence or absence of these words has no effect upon the program. 

2. The reserved words THRU and THROUGH are interchangeable. 

3. GnuCOBOL always behaves as if the WITH DUPLICATES IN ORDER clause is specified, 
even if it isn’t. 
While any COBOL implementation’s sort or merge facilities guarantee that records 
with duplicate key values will be in proper sequence with regard to other records 
with different key values, they generally make no promises as to the resulting relative 
sequence of records having duplicate key values with one another. 
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Some COBOL implementations provide this optional clause to force their sort and 
merge facilities to retain duplicate key-value records in their original input sequence, 
relative to one another. 


4. The sort-file-1 named on the SORT statement must be defined using a sort description 
(SD (see [File/Sort-Description], page 124)). This file is referred to in the remainder of 
this discussion as the sort work file. 


5. If specified, file-name-1 and _ file-name-2 must reference ORGANIZATION LINE 
SEQUENTIAL (see [ORGANIZATION LINE SEQUENTIAL], page 111) or 
ORGANIZATION SEQUENTIAL (see [ORGANIZATION SEQUENTIAL], page 109) files. 
These files must be defined using a file description (FD (see [File/Sort-Description], 
page 124)). The same file(s) may be used for file-name-1 and file-name-2. 


6. The identifier-1 ... field(s) must be defined as field(s) within a record of sort-file-1. 
7. A sort work file is never opened or closed. 


8. The sorting process works in three stages — the Input Stage, the Sort Stage and the 
Output Stage. 


9. The following points pertain to the Input Stage: 


A. The data to be sorted is loaded into the sort work file either by copying the entire 
contents of the file(s) named on the USING clause (done automatically by the sort) 
or by utilizing an input procedure. 


B. When USING is specified, none of the file-name-1 files may be open at the time 
the SORT statement is executed. 


C. When an input procedure is used, the procedure(s) specified on the INPUT 
PROCEDURE clause will be invoked as if by a procedural PERFORM statement (see 
[Procedural PERFORM], page 360) with no VARYING, TIMES or UNTIL options 
specified. Records will be loaded into the sort work file — one at a time — within 
the input procedure using the RELEASE statement (see [RELEASE], page 371). 
This, by the way, is how you could sort the contents of relative or indexed files. 


A GO TO statement (see [GO TO], page 335) that transfers control out of the input 
procedure will terminate the SORT statement but allows the program to continue 
executing from the point where the GO TO statement transferred control to. Once 
an input procedure has been “aborted” using a GO TO it cannot be resumed, and 
the contents of the sort work file are lost. You may, however, re-execute the SORT 
statement itself.’ 


An input procedure should be terminated in the same way a procedural PERFORM 
statement would be. 
Neither a another file-based SORT statement nor a MERGE statement may be exe- 
cuted within the input procedure unless those statements utilize a different sort or 
merge work file. 

D. Once the input procedure terminates, the input phase is complete. 


E. As data is loaded into the sort work file, it is actually being buffered in dynamically- 
allocated memory. Only if the amount of data to be sorted exceeds the amount 


: Using a GO TO statement to prematurely terminate a sort, or re-starting a previously-cancelled sort is 
not considered good programming style and should be avoided. 
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10. The 
A. 


11. The 
A. 


of available sort memory (128 MB) will actual disk files be allocated and utilized. 
There is a COB_SORT_MEMORY run-time environment variable (see [Run Time En- 
vironment Variables], page 654) that you may use to allocate more or less memory 
to the sorting process. 


following points pertain to the Sort Stage: 


The sort will take place by arranging the data records in the sequence defined 
by the KEY specification(s) on the SORT statement according to the COLLATING 
SEQUENCE specified on the SORT (if any) or — if none was defined — the PROGRAM 
COLLATING SEQUENCE (see [OBJECT-COMPUTER], page 90). Keys may be any 
supported data type and USAGE (see [USAGE], page 232) except for level-78 or 
level-88 data items. 


For example, let’s assume we’re sorting a series of financial transactions. The 
SORT statement might look like this: 


SORT Sort-File 
ASCENDING KEY Transaction-Date 
ASCENDING KEY Account-Number 
DESCENDING KEY Transaction-Amount 


The effect of this statement will be to sort all transactions into ascending order of 
the date the transaction took place (oldest first, newest last). Unless the business 
running this program is going out of business, there are most-likely many trans- 
actions for any given date. Therefore, within each grouping of transactions all 
with the same date, transactions will be sub-sorted into ascending sequence of the 
account number the transactions apply to. Since it’s quite possible there might be 
multiple transactions for an account on any given date, a third level sub-sort will 
arrange all transactions for the same account on the same date into descending 
sequence of the actual amount of the transaction (largest first, smallest last). If 
two or more transactions of $100.00 were recorded for account #12345 on the 31** 
of August 2009, those transactions will be retained in the order in which they were 
loaded into the sort work file. 


Should disk work files be necessary due to the amount of data being sorted, they 
will be automatically allocated to disk in a folder defined by the TMPDIR run- 
time environment variable, TMP run-time environment variable or TEMP run-time 
environment variable run-time environment variables (see [Run Time Environment 
Variables], page 654) (checked for existence in that sequence). These disk files will 
be automatically purged upon SORT termination or program execution termination 
(normal or otherwise). 


following points pertain to the Output Stage: 


Once the sort stage is complete, a copy of the sorted data will be written to each 
file-name-2 if the GIVING clause was specified. None of the file-name-2 files can 
be open at the time the sort is executed. 


. When an output procedure is used, the procedure(s) specified on the OUTPUT 


PROCEDURE clause will be invoked as if by a procedural PERFORM statement (see 
[Procedural PERFORM], page 360) with no VARYING, TIMES or UNTIL options spec- 
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ified. Records will be retrieved from the sort work file — one at a time — within 
the output procedure using the RETURN statement (see [RETURN], page 373). 


A GO TO statement (see [GO TO], page 335) that transfers control out of the output 
procedure will terminate the SORT statement but allows the program to continue 
executing from the point where the GO TO statement transferred control to. Once 
an output procedure has been “aborted” using a GO TO it cannot be resumed, and 
the contents of the sort work file are lost. You may, however, re-execute the SORT 
statement itself. USING A GO TO statement? 

An output procedure should be terminated in the same way a procedural PERFORM 
statement would be. 

Neither a another file-based SORT statement nor a MERGE statement may be exe- 
cuted within the output procedure unless those statements utilize a different sort 
or merge work file. 


C. Once the output procedure terminates, the sort is complete. 


2 To prematurely terminate a sort, or re-starting a previously-cancelled sort is not considered good pro- 
gramming style and should be avoided. 
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7.8.41.2. Table SORT 


[ 


Table SORT Syntax } 


SORT table-name-1 


{ ON { ASCENDING } KEY identifier-1... }... 
Aen a ae i: 


The DUPLICATES clause is syntactically recognized but is otherwise non-functional. 


This format of the SORT statement sorts relatively small quantities of data — namely 


data contained in a data division table — according to one or more key fields. 


1. 


The reserved words IN, IS, KEY, ON, ORDER, SEQUENCE and WITH are optional and may 
be omitted. The presence or absence of these words has no effect upon the program. 


GnuCOBOL always behaves as if the WITH DUPLICATES IN ORDER clause is specified, 
even if it isn’t. 

While any COBOL implementation’s sort or merge facilities guarantee that records 
with duplicate key values will be in proper sequence with regard to other records 
with different key values, they generally make no promises as to the resulting relative 
sequence of records having duplicate key values with one another. 


Some COBOL implementations provide this optional clause to force their sort and 
merge facilities to retain duplicate key-value records in their original input sequence, 
relative to one another. 


The table-name-1 data item must be a table defined in any data division section except 
the report or screen sections. 


The data within table-name-1 will be sorted in-place (i.e. no sort file is required). 


5. The sort will take place by rearranging the data in table-name-1 into the sequence 


defined by the KEY specification(s) on the SORT statement, according to the COLLATING 
SEQUENCE specified on the SORT (if any) or — if none was defined — the PROGRAM 
COLLATING SEQUENCE (see [OBJECT-COMPUTER], page 90). Keys may be any sup- 
ported data type and USAGE (see [USAGE], page 232) except for level-78 or level-88 
data items. 


If you are sorting table-name-1 for the purpose of preparing the table for use with a 
SEARCH ALL statement (see [SEARCH ALL], page 379), care must be taken that the 
KEY specifications on the SORT agree with those in the table’s definition. 
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7. Although the specification of one or more KEY clauses is optional, currently, a table 
sort with no KEY specification(s) made on the SORT statement is unsupported by Gnu- 
COBOL and will be rejected by the compiler. 
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7.8.42. START 


START Syntax 


START file-name-1 


+] 
} 
LAST $ 
} 
identifier-1 } 


KEY { IS EQUAL TO | IS = | EQUALS 


IS GREATER THAN | IS > 


t 
bs 
t 
t 
IS GREATER THAN OR EQUAL TO | IS >= } 
Suelo +, Bee eee } 

IS NOT LESS THAN } 
ae ee t 

iy 

t 

i 

t 

i: 


IS LESS THAN | IS < 


IS LESS THAN OR EQUAL TO | IS <= 


AAA A NAA AAA 


IS NOT GREATER THAN 


[ WITH {SIZE} arithmetic-expression ] 


[ {LENGTH} arithmetic-expression ] 


The START statement defines the logical starting point within a relative or indexed file for 
subsequent sequential read operations. It positions an internal logical record pointer to a 
particular record in the file, but does not actually transfer any of that record’s data into 
the record buffer. 
1. The reserved words IS, THAN and TO are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


2. To use this statement, file-name-1 must be an ORGANIZATION RELATIVE (see 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


398 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


[ORGANIZATION RELATIVE], page 113) or ORGANIZATION INDEXED (see 
[ORGANIZATION INDEXED], page 115) file that must have been defined with 
an ACCESS MODE DYNAMIC or ACCESS MODE SEQUENTIAL in its SELECT statement (see 
[SELECT], page 104). 

At the time this statement is executed, file-name-1 must be open in either INPUT or 
I-0 (see [File OPEN Modes], page 359) mode. 

If file-name-1 is a relative file, identifier-1 must be the defined RELATIVE KEY of the 
file. 

If file-name-1 is an indexed file, identifier-1 must be the defined RECORD KEY of the file 
or any of the ALTERNATE RECORD KEY fields for the file. 

If no FIRST, LAST or KEY clause is specified, KEY IS EQUAL TO xxx will be assumed, 
where xxx is the defined RELATIVE KEY of (if file-name-1 is a relative file) or the defined 
RECORD KEY (if file-name-1 is an indexed file). 

After successful execution of a START statement, the internal logical record pointer 
into the file-name-1 data will be positioned to the record which satisfied the actual or 
implied FIRST, LAST or KEY clause specification, as follows: 


FIRST the logical record pointer will point to the first record in the file. 
LAST the logical record pointer will point to the last record in the file. 
KEY (specified or implied), and the relation used is. Warning: Later versions of 


the compiler may well not use implied, so always specify it and it makes 
the code easier to read any way. 


SIZE WITH SIZE or LENGTH arithmetic-expression specifies the number of char- 
acters in the key to be used in the positioning process. 


LENGTH WITH LENGTH or SIZE arithmetic-expression specifies the number of char- 
acters in the key to be used in the positioning process. 


SIZE and LENGTH are interchangeable and mean exactly the same. 


EQUAL TO, GREATER THAN or GREATER THAN OR EQUAL TO (or equivalent) 
the logical record pointer will be specified to the first record 
satisfying the relation condition; to identify this record. The 
file’s contents are searched in a first-to-last (in sequence of the 
key implied by the KEY clause), provided the relation is 


LESS THAN, LESS THAN OR EQUAL TO or NOT GREATER THAN (or equivalent) 
the logical record pointer will be specified to the last record 
satisfying the relation condition; to identify this record. The 
file’s contents are searched in a last-to-first (in sequence of the 
key implied by the KEY clause) 


The next sequential READ statement will read the record that is pointed to by the logical 
record pointer. 

The optional INVALID KEY and NOT INVALID KEY clauses may be used to detect and 
react to the failure or success, respectively, by detecting non-zero (typically 23 = key 
not found = record not found) and 00 file status codes, respectively. See [File Status 
Codes], page 107, for additional information. 
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7.8.43. STOP 
STOP Syntax } 

STOP { RUN [ { RETURNING|GIVING { literal-1 } +] } 
RO me. ile eur ars { identifier-1 } ko} 

{ { re 8p 

{ { WITH { ERROR } STATUS [ { literal-2 Polish. ok 

{ { fear Cag } { identifier-2 } } } 

{ { { NORMAL } +} 5 

, iF 

{ literal-3 } 


The STOP statement suspends program execution. Some options will allow program execu- 
tion to resume while others return control to the operating system. 


1. 


The reserved words STATUS and WITH are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


2. The reserved words RETURNING and GIVING are interchangeable. 


10. 
11. 


. The RUN clause halts the program without displaying any special message to that effect. 


The literal-3 clause displays the specified text on the SYSOUT/STDOUT device, waits for 
the user to press the Enter key and then — once the key has been pressed — allows 
the program to continue execution. 

The optional RETURNING clause provides the opportunity to return a numeric value to 
the operating system (an exit status). The manner in which the exit status may be 
interrogated by the operating system varies, but Windows can use ,ERRORLEVELY to 
query the exit status while Unix shells such as sh, bash and ksh can query the exit 
status as $7. Other Unix shells may have different ways to access return code values. 


The STATUS clause provides another means of returning an exit status. Using the 
STATUS clause is functionally equivalent to using the RETURNING clause. 


Using the STATUS clause without a literal-2 or identifier-2 will return an exit status of 
0 if the NORMAL keyword is used or a 1 if ERROR was specified. 


Your program will always return an exit status, even if no RETURNING or STATUS clause 
is specified. In the absence of the use of these clauses, the value in the RETURN-CODE 
special register (see [Special Registers], page 265) at the time the STOP statement is 
executed will be used as the exit status. 

Any programmer-defined exit procedure (established via the CBL_EXIT_PROC built-in 
system subroutine (see [CBL_EXIT_PROC], page 566)) will be executed by STOP RUN, 
but not by STOP literal-3. 


Valid return code values can be in the range -2147483648 to +2147483647. 


The three code snippets below are all equivalent. They show different ways in which 
a GnuCOBOL program may be coded to pass an exit status value of 16 back to the 
operating system and then halt. 
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STOP RUN RETURNING 16 


MOVE 16 TO RETURN-CODE 
STOP RUN 


STOP RUN WITH ERROR STATUS 16 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 401 


7.8.44. STRING 


[ 


STRING Syntax ] 
STRING 
{ { literal-1 } [ DELIMITED BY { SIZE i eed ee 
{ identifier-1 } ~“"77~7"77~ ; aa } 
{ literal-2 } 
{ identifier-2 } 


INTO identifier-3 


[ WITH POINTER identifier-4 ] 


[ NOT ON OVERFLOW imperative-statement-2 ] 


END-STRING ] 


The STRING statement is used to concatenate all or a part of one or more strings together, 
forming a new string. 


1. 


The reserved words BY, ON and WITH are optional and may be omitted. The presence 
or absence of these words has no effect upon the program. 


All literals and identifiers (except for identifier-4) must be explicitly or implicitly de- 
fined with a USAGE (see [USAGE], page 232) of DISPLAY. Any of the identifiers may be 
group items. 


The POINTER data item — identifier-4 — must be a non-edited elementary integer 
numeric data item with a value greater than zero. 


Each literal-1 / identifier-1 will be referred to as a source item. The receiving data 
item is identifier-3. 


The STRING statement’s processing is based upon a_ current character pointer. The 
initial value of the current character pointer will be the value of identifier-4 at the 
time the STRING statement began execution. If no POINTER clause is coded, a value 
of 1 (meaning “the 1** character position”) will be assumed for the current character 
pointer’s initial value. 


For each source item, the contents of the sending item will be copied — character-by- 
character — into identifier-3 at the character position specified by the current char- 
acter pointer. After each character is copied, the current character pointer will be 
incremented by 1 so that it points to the position within identifier-3 where the next 
character should be copied. 
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The DELIMITED BY clause specifies how much of each source item will be copied into 

identifier-3._ DELIMITED BY SIZE (the default if no DELIMITED BY clause is specified) 

causes the entire contents of the source item to be copied into identifier-3. 

Using DELIMITED BY literal-2 or DELIMITED BY identifier-2 causes only the con- 

tents of the source item up to but not including the character sequence specified by the 

literal or identifier to be copied. 

STRING processing will cease when one of the following occurs: 

A. The initial value of the current character pointer is less than 1 or greater than the 
number of characters in identifier-3, or... 

B. The value of the current character pointer exceeds the size of identifier-3 at the 
point the STRING statement wants to copy a character into identifier-3, or... 

C. All sending items have been fully processed 

If event A occurs, identifier-3 will remain unchanged. 

The occurrence of either event A or B triggers what is referred to as an overflow 

condition. 

The identifier-3) is neither automatically initialized (to spaces or any other value) at 

the start of a STRING statement nor will it be space-filled should the total number of 

sending item characters copied into it be less than its size. You may explicitly initialize 

identifier-3 yourself via the INITIALIZE (see [INITIALIZE], page 339) or MOVE (see 

[MOVE], page 352) statements before executing the STRING if you wish. 

The optional ON OVERFLOW and NOT ON OVERFLOW clauses may be used to detect and 


react to the occurrence or not, respectively, of an overflow condition. See [ON OVER- 
FLOW + NOT ON OVERFLOW\, page 260, for additional information. 
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7.8.45. SUBTRACT 


7.8.45.1. SUBTRACT FROM 


[ SUBTRACT FROM Syntax 


SUBTRACT { literal-1 }... FROM { identifier-2 
phat igo { identifier-1 } Tete es 


[ ROUNDED [ MODE IS { AWAY-FROM-ZERO 
Cadediedieadeadied ~nwwe { www nwnwnwnwnwnwnwnwnwwwe 


A4 

a 

2 

2 eS 

2 

> 

2 
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| 

2 eS 

2S 

2 LS 

wie 

| 

es 

eas) 

2 oO 

9 

2 4 

IN 

> 

=) 

es) 

wwwy 
— 
Lael 
Ww 


A 
2g 
2g 
z 
z 
z 
zg 
zg 
2g 
2g 
z 
PPP YYYYYwy 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-SUBTRACT ] 


This format of the SUBTRACT statement generates the arithmetic sum of all arguments 
that appear before the FROM (identifier-1 or literal-1) and subtracts that sum from each 
identifier-2. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be numeric unedited data items. 
3. literal-1 must be a numeric literal. 


4. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 
will control how non-integer results will be saved. 


5. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
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this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 
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7.8.45.2. SUBTRACT GIVING 


SUBTRACT GIVING Syntax 


SUBTRACT { literal-1 }... FROM identifier-2 
gi apce tig box { identifier-1 } aa 


GIVING { identifier-3 
[ ROUNDED [ MODE IS { AWAY-FROM-ZERO PT pas 
BE OS? E pga aaa } 


wy 


A 

cy 

z 

z 

z 

2g 

2g 

zg 

2g 

2 

2g 
Pee YY YYYy 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-SUBTRACT ] 


The SUBTRACT GIVING statement generates the arithmetic sum of all arguments that appear 
before the FROM (identifier-1 or literal-1), subtracts that sum from the contents of identifier- 
2 and then replaces the contents of the identifiers listed after the GIVING (identifier-3) with 
that result. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


Both identifier-1 and identifier-2 must be numeric unedited data items. 
literal-1 must be a numeric literal. 
identifier-3 must be a numeric (edited or unedited) data item. 


The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 
will control how non-integer results will be saved. 


OP ae ee aS 
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6. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 
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7.8.45.3. SUBTRACT CORRESPONDING 


SUBTRACT CORRESPONDING Syntax 


SUBTRACT CORRESPONDING identifier-1 FROM identifier-2 
[ ROUNDED [ MODE IS { AWAY-FROM-ZERO 
 edadediediadiad ~nwnwe { nnn nwnwnwnwnwnwnwnwnwnwne 


AA 

a 

> 

2 eS 

= 

> 

2 

ie 

2 4 

2 eS 

ae 

2 LS 

RK 

aan | 

2 Hy 

eas) 

2 oO 

9 

| 

IN 

2 

a) 

en) 

wwwy 
ed 
=) 


A 

zg 

z 

z 

ey 

cy 

2g 

z 

z 

2g 

2g 
PMS YY YY YY 


[ NOT ON SIZE ERROR imperative-statement-2 ] 


[ END-SUBTRACT ] 


The SUBTRACT CORRESPONDING statement generates code equivalent to individual SUBTRACT 
FROM statements for corresponding matches of data items found subordinate to the two 
identifiers. 


1. The reserved words IS and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 


2. Both identifier-1 and identifier-2 must be group items. 

3. See [CORRESPONDING], page 258, for information on how corresponding matches 
will be found between identifier-1 and identifier-2. 

4. The optional ROUNDED (see [ROUNDED], page 261) clause available to each identifier-2 


will control how non-integer results will be saved. 


5. The optional ON SIZE ERROR and NOT ON SIZE ERROR clauses may be used to detect and 
react to the failure or success, respectively, of an attempt to perform a calculation. In 
this case, failure is defined as being an identifier-2 with an insufficient number of digit 
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positions available to the left of any implied decimal point. See [ON SIZE ERROR + 
NOT ON SIZE ERROR|, page 261, for additional information. 
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7.8.46. SUPPRESS 


SUPPRESS Syntax ] 


SUPPRESS PRINTING 


The SUPPRESS statement causes the presentation of a report group to be suppressed. 
1. The reserved word PRINTING is optional and may be omitted. The presence or absence 
of this word has no effect upon the program. 
2. This statement may only appear within a USE BEFORE REPORTING procedure (in 
DECLARATIVES (see [DECLARATIVES], page 254)). 
3. SUPPRESS only prevents the presentation of the report group within whose USE BEFORE 
REPORTING procedure the statement occurs. 
4. This statement must be executed each time presentation of the report group is to be 
suppressed. 
5. When a report group’s presentation is suppressed, none of the following operations for 
the report will take place: 
A. Actual presentation of the report group in question. 
B. Processing of any LINE (see [LINE], page 183) clauses within the report group in 
question. 
C. Processing of the NEXT GROUP (see [NEXT GROUP], page 187) clause (if any) 
within the report group in question. 
D. Any modification to the LINE-COUNTER special register (see [Special Registers], 
page 265). 
E. Any modification to the PAGE-COUNTER special register. 
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7.8.47. TERMINATE 


TERMINATE Syntax 


TERMINATE report-name-1... 


The TERMINATE statement causes the processing of the specified report(s) to be completed. 


1. 


Each report-name-1 must be the name of a report having an RD (see [REPORT SEC- 
TION], page 135) defined for it. 


The specified report name(s) must be currently initiated (via INITIATE (see 
[INITIATE], page 343)) and cannot yet have been terminated. 


The TERMINATE statement will present each CONTROL FOOTING (if any), in reverse se- 
quence of the control hierarchy, starting with the most minor up to FINAL (if any). Dur- 
ing the presentation of these groups and the processing of any USE BEFORE REPORTING 
procedures for those groups, the prior set of control data item values will be available, 
as though a control break had been detected at the most major control data name. 


During the presentation of the CONTROL FOOTING groups, any necessary PAGE FOOTING 
and PAGE HEADING groups will be presented as well. 


5. Finally,the REPORT FOOTING group, if any, will be presented. 
6. If an INITIATE is followed by a TERMINATE with no intervening GENERATE (see 


[GENERATE], page 332) statements (all pertaining to the same report, of course), no 
report groups will be presented to the output file. 
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7.8.48. TRANSFORM 


TRANSFORM identifier-1 CHARACTERS FROM { literal-1 } TO { literal-2 


TRANSFORM Syntax ] 
} 
ciate cee ~~~~ £ identifier-2 } ~~ { identifier-3 } 


The TRANSFORM statement scans a data item performing a series of mono-alphabetic substi- 
tutions, defined by the arguments before and after the TO clause. 

1. Both literal-1 and/or literal-2 must be alphanumeric literals. 

2. All of identifier-1, identifier-2 and identifier-3 must either be group items or alphanu- 
meric data items. Numeric data items with a USAGE (see [USAGE], page 232) of 
DISPLAY are accepted, but will generate warning messages from the compiler. 

3. The TRANSFORM statement will replace characters within identifier-1 that are found in 
the string specified before the TO keyword with the corresponding characters from the 
string specified after the TO keyword. 

4. Usage of word CHARACTERS has no effect on operations other than for appearance. 

5. This statement exists within GnuCOBOL to provide compatibility with COBOL pro- 
grams written to pre-1985 standards. The TRANSFORM statement was made obsolete in 
the 1985 standard of COBOL, having been replaced by the CONVERTING clause of the 
INSPECT statement (see [INSPECT], page 344). New programs should be coded to use 
INSPECT CONVERTING rather than TRANSFORM. 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


412 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


7.8.49. UNLOCK 


UNLOCK Syntax ] 


UNLOCK filename-1 RECORD| RECORDS 


This statement synchronizes any as-yet unwritten file I/O buffers to the specified file (if 
any) and releases any record locks held for records belonging to file-name-1. 


1. 


The reserved words RECORD and RECORDS are optional and may be omitted. The pres- 
ence or absence of these words has no effect upon the program. 


2. If file-name-1 is a Sort/Merge work file, no action will be taken. 


3. Not all GnuCOBOL implementations support locking. Whether they do or not depends 


upon the operating system they were built for and the build options that were used 
when GnuCOBOL was generated. When a program using one of those GnuCOBOL 
implementations issues an UNLOCK, it will ignored. There will be no compiler message 
issued. Buffer syncing, if needed, will still occur. 

For GnuCOBOL UNLOCK is implied in GnuCOBOL on file close so there’s no use to 
do it afterwards. A CLOSE will always trigger syncing the file to disk, too. 

Doing UNLOCK before a close, will explicit unlock any records with a lock when 
running on INDEXED files, for other files it will release any locks on the file if it 
wasn’t opened for exclusive locking and will trigger syncing to disk (not done for any 
INDEXED file). 

When using Linux and for that matter most *nix platforms, the system maintains it’s 
own cache and buffers for file processing so there can and most likely will be a short 
delay before all data is written out to disk. 


See [Record Locking], page 59, for additional information on record locking. 
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7.8.50. UNSTRING 


UNSTRING Syntax 


[ 


UNSTRING identifier-1 
DELIMITED. BY {4 [ ALL] diteral-1 } [OR.{ [-ALL.J Titeral-2°}:].«. 


ir ai ke { rae } ae 8 at } 
{ identifier-2 } { identifier-3 } 


INTO { identifier-4 
“~~~ [T DELIMITER IN identifier-5 ] [ COUNT IN identifier-6 ] }... 


[ WITH POINTER identifier-7 ] 

[ TALLYING IN identifier-8 ] 

[ ON OVERFLOW imperative-statement-1 ] 

[ NOT ON OVERFLOW imperative-statement-2 ] 


END-UNSTRING ] 


The UNSTRING statement parses a string, extracting any number of sub strings from it. 


1. 


The reserved words BY, IN and ON are optional and may be omitted. The presence or 
absence of these words has no effect upon the program. 

identifier-1 through identifier-5 must be explicitly or implicitly defined with a USAGE 
(see [USAGE], page 232) of DISPLAY. Any of those identifiers may be group items. 
Both literal-1 and literal-2 must be alphanumeric literals. 

Each of identifier-6, identifier-7 and identifier-8 must be elementary non-edited integer 
numeric items. 

At the time the UNSTRING statement begins execution, identifier-7 must have a value 
greater than 0. 

identifier-1 will be referred to as the source string and each identifier-4 will be referred 
to as a destination field in the following discussions. 

The UNSTRING statement’s processing is based upon a current character pointer, the 
initial value of which will be the value of identifier-7 at the time the UNSTRING statement 
began execution. If no POINTER clause is coded, a value of 1 (meaning “the 1° character 
position” ) will be assumed for the current character pointer’s initial value. 

The source string will be parsed into sub strings starting from the current charac- 
ter pointer position. Sub strings are identified by using the various delimiter strings 
specified on the DELIMITED BY clause as inter-sub string separators. 
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9. 


10. 
11. 


12. 


13. 


14. 


15. 


16. 


Lh 


18. 


19. 


Using the ALL option allows a delimiter sequence to be an arbitrarily long sequence 
of occurrences of the delimiter literal whereas its absence treats each occurrence as a 
separate delimiter. When multiple delimiters are specified, they will be looked for in 
the source string in the sequence in which they are coded. 


Two consecutive delimiter sequences will identify a null sub string. 


Identified sub strings will be moved into each destination field in the sequence they 
are identified; values moved into a destination field will be truncated if the sub string 
length exceeds the destination field length, or padded with spaces if the destination field 
length exceeds the sub string length. Both truncation and padding will be controlled 
by the presence or absence of a JUSTIFIED (see [JUSTIFIED], page 179) clause on the 
destination field. 


Each destination field may have an optional DELIMITER clause. If a DELIMITER clause 
is specified, identifier-5 will have the delimiter character string used to identify the 
sub string for the destination field moved into it. If a destination field was not altered 
(because an insufficient number of sub strings were identified), identifier-5 for that 
destination field will also be unchanged. 


Each destination field may have an optional COUNT clause. If a COUNT clause is specified, 
identifier-6 will have the size of the sub string (in characters) for the destination field 
moved into it. If a destination field was not altered (because an insufficient number of 
sub strings were identified), identifier-6 for that destination field will also be unchanged. 
If a TALLYING clause is coded, identifier-8 will be incremented by 1 each time a desti- 
nation field is populated. 

None of identifier-4, identifier-5, identifier-6, identifier-7 or identifier-8 are initialized 
by the UNSTRING statement. You need to do that yourself via a MOVE (see [MOVE], 
page 352) or INITIALIZE statement (see [INITIALIZE], page 339). 


UNSTRING processing will cease when one of the following occurs: 


A. The initial value of the current character pointer is less than 1 or greater than the 
number of character positions in identifier-1, or... 


B. All destination fields have been fully processed 


If event A occurs, none of the destination field contents (or the contents of their 
DELIMITER or COUNT identifiers) will be changed. 


An overflow condition exists if either event A occurs, or if event B occurs with at least 
one character position in identifier-1 not having been processed. 


The optional ON OVERFLOW and NOT ON OVERFLOW clauses may be used to detect and 
react to the occurrence or not, respectively, of an overflow condition. See [ON OVER- 
FLOW + NOT ON OVERFLOW\, page 260, for additional information. 


The following sample program illustrates the UNSTRING statement statement. 


IDENTIFICATION DIVISION. 

PROGRAM-ID. DEMOUNSTRING. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 Full-Name PIC X(40). 
O1 Parsed-Info. 


Chapter 7 - PROCEDURE DIVISION 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 415 


05 
05 
05 
05 
05 
05 
05 
05 
05 
05 
PROCED 


Pi. PERFORM UNTIL EXIT 


DI 


DI 


DI 


DI 
END- 
DISP 
STOP 


Last-Name 
First-Name 
MI 

Delim-LN 
Delim-FN 
Delim-MI 
Count-LN 
Count-FN 
Count-MI 
Tallying-Ctr 
URE DIVISION. 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


X(15). 
X(15). 
X(1). 
X(1). 
X(1). 
X(1). 


BINARY-CHAR. 
BINARY-CHAR. 
BINARY-CHAR. 
BINARY-CHAR. 


DISPLAY "Enter Full Name (null quits):" 
WITH NO ADVANCING 


ACCEPT Full-Name 


IF Full-Name = SPACES 


EXIT PERFORM 
END-IF 


INITIALIZE Parsed-Info 
UNSTRING Full-Name 


DELIMITED BY ", 
OR tae 


OR ALL SPACES 


INTO Last-Name 


DELIMITER IN Delim-LN 
COUNT IN Count-LN 


First-Name 


DELIMITER IN Delim-FN 
COUNT IN Count-FN 


MI 


DELIMITER IN Delim-MI 
COUNT IN Count-MI 
TALLYING Tallying-Ctr 


SPLAY "First-Name=" First-Name 


" Delim=’" 

"2 Count=" 
SPLAY "MI 

" Delim=’" 

"2 Count=" 


SPLAY "Last-Name = 


" Delim=’" 
"2 Count=" 
SPLAY "Tally= 
PERFORM 
LAY "Bye!" 
RUN 


15 January 2023 


Delim-FN 
Count-FN 
MI " 

Delim-MI 
Count-MI 
Last-Name 
Delim-LN 
Count-LN 


Tallying-Ctr 
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The following is sample output from the program: 


Enter Full Name (null quits):Cutler, Gary L 


First-Name=Gary Delim=’ ’ Count=+004 
MI =L Delim=’ ’ Count=+001 
Last-Name =Cutler Delim=’,’ Count=+006 
Tally= +003 

Enter Full Name (null quits) :Snoddgrass,Throckmorton,P 
First-Name=Throckmorton Delim=’,’ Count=+012 
MI =P Delim=’ ’ Count=+001 
Last-Name =Snoddgrass Delim=’,’ Count=+010 
Tally= +003 

Enter Full Name (null quits):Munster Herman 
First-Name=Herman Delim=’ ’ Count=+006 
MI = Delim=’ ’ Count=+000 
Last-Name =Munster Delim=’ ’ Count=+007 
Tally= +002 

Enter Full Name (null quits): 

Bye! 
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7.8.51. WRITE 


WRITE Syntax 


WRITE record-name-1 
[ FROM { literal-1 el 
~~~~ £ identifier-1 } 


[ WITH [ NO ] LOCK ] 


[ { BEFORE } ADVANCING { { literal-2 } LINE|LINES } ] 


5 aemtei ane } { { identifier-2 } 
{ AFTER } { PAGE J 
pe ete: | eae } 

{ mnemonic-name-1 } 


[ AT END-OF-PAGE|EOP imperative-statement-1 ] 


[ NOT AT END-OF-PAGE|EOP imperative-statement-2 ] 


[ INVALID KEY imperative-statement-3 ] 


The WRITE statement writes a new record to an open file. 


1. 


The reserved words ADVANCING, AT, KEY, LINE, LINES and WITH are optional and may 
be omitted. The presence or absence of these words has no effect upon the program. 


The reserved words END-OF-PAGE and EOP are interchangeable. 


The record-name-1 specified on the statement must be defined as an 01-level record 
subordinate to the File Description (FD (see [File/Sort-Description], page 124)) of a file 
that is currently open for OUTPUT (see [File OPEN Modes], page 359), EXTEND or I-O. 


The optional FROM clause will cause literal-1 or identifier-1 to be automatically moved 
into record-name-1 prior to writing record-name-1’s contents to the appropriate file. 
If this clause is not specified, it is the programmer’s responsibility to populate record- 
name-1 with the desired data prior to executing the WRITE. 


The optional LOCK options may be used to manually control access to the just-written 
record by other programs while this program is running. See [Record Locking], page 59, 
to review the various record locking behaviour. 


15 January 2023 Chapter 7 - PROCEDURE DIVISION 


418 


6. 


8. 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


The optional INVALID KEY and NOT INVALID KEY clauses may be used when writing to 
relative or indexed files to detect and react to the failure (non-zero file status code) or 
success (00 file status code), respectively, of the statement. See [File Status Codes], 
page 107, for additional information. 


When WRITE is used against an ORGANIZATION LINE SEQUENTIAL (see 
[ORGANIZATION LINE SEQUENTIAL], page 111) file, with or without 
the LINE ADVANCING (see [LINE ADVANCING], page 15) option, an end-of-record 
delimiter character sequence will be written to the file to signify where one record ends 
and the next record begins. This delimiter sequence will be either of the following: 


e A line-terminator sequence consisting of an ASCII carriage-return/line-feed char- 
acter sequence (X’ODOA’) if you are running a MinGW or native Windows build 
of GnuCOBOL 


e A line-terminator sequence consisting of an ASCII line-feed character (X’0A’) if 
you are running a Cygwin, Linux, Unix or OSX build of GnuCOBOL 


The following points pertain to the use (or not) of the ADVANCING clause: 


A. Using this clause with any organization other than ORGANIZATION LINE 
SEQUENTIAL will either be rejected outright by the compiler (relative or indexed 
files) or may introduce unwanted characters into the file (ORGANIZATION 
SEQUENTIAL (see [ORGANIZATION SEQUENTIAL], page 109)). 


B. If no ADVANCING clause is specified on a WRITE to a line-advancing file, AFTER 
ADVANCING 1 LINE will be assumed; on other than line-advancing files, BEFORE 
ADVANCING 1 LINE will be assumed. 


C. When BEFORE ADVANCING is used (or implied), the record is written to the file 
before the ADVANCING action writes line-terminator characters to the file. 


D. If AFTER ADVANCING is used (or implied), the ADVANCING action writes 
line-terminator characters to the file and then the record data is written to the 
file. 


E. The ADVANCING n LINES clause will introduce the specified number of 
line-terminator character sequences into the file either before the written record 
(AFTER ADVANCING) or after the written record (BEFORE ADVANCING). 


F. If the LINAGE (see [File/Sort-Description], page 124) clause is absent from the file’s 
FD: 


a. The ADVANCING PAGE clause will introduce an ASCII formfeed character into 
the file either before the written record (AFTER PAGE) or after the written 
record (BEFORE PAGE). 


b. Management of areas on the printed page such as top-of page headers, bottom- 
of-page footers, dealing with “full page” situations and the like are the com- 
plete responsibility of the programmer. 

G. If the LINAGE clause is present in the file’s FD: 

a. The ADVANCING PAGE clause will introduce the appropriate number of line- 
terminator character sequences into the file either before the written record 
(AFTER ADVANCING) or after the written record (BEFORE ADVANCING) so as to 
force the printer to automatically advance to a new sheet of paper when the 
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file prints. No formfeed characters will be generated when LINAGE is specified 
— instead, it is assumed that the printer to which the report will be printed 
will be loaded with special forms that conform to the specifications defined 
by the LINAGE clause. 


b. Management of areas on the printed page such as top-of page headers, bottom- 
of-page footers, dealing with “full page” situations and the like are now the 
joint responsibility of the programmer and the GnuCOBOL run-time library, 
which provides tools such as the LINAGE-COUNTER special register (see [Special 
Registers], page 265) and the END-OF-PAGE clause to deal with page format- 
ting issues. 

c. The AT END-OF-PAGE clause will be triggered, thus executing imperative- 
statement-1 (see [Imperative Statement], page 718), if the WRITE statement 
introduces a data line or line-feed character into the file at a line position 
within the Page Footer area defined by the LINAGE clause. The NOT AT 
END-OF-PAGE clause will be triggered (thus executing imperative-statement-2) 
if no end-of-page condition occurred during the WRITE. 


End of Chapter 7 — PROCEDURE DIVISION 
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8. Functions 


8.1. Intrinsic Functions 


GnuCOBOL supports a wide variety of “intrinsic functions” that may be used anywhere in 
the PROCEDURE DIVISION where a literal is allowed. For example: 


MOVE FUNCTION LENGTH(Employee-Last-Name) TO Employee-LN-Len 


Note how the word FUNCTION is part of the syntax when you use an intrinsic function. 
You can use intrinsic functions without having to include the reserved word FUNCTION via 
settings in the REPOSITORY (see [REPOSITORY], page 101) paragraph. You may accom- 
plish the same thing by specifying the -fintrinsics switch to the GnuCOBOL compiler 
when you compile your programs. 


User-written functions (see [Subprogram Types], page 675) never require the FUNCTION 
keyword when they are executed, because each user-written function a program uses must 
be included in that program’s REPOSITORY paragraph, which therefore makes the FUNCTION 
keyword optional. 


The following intrinsic functions, known to other “dialects” of COBOL, are defined to 
GnuCOBOL as reserved words but are not otherwise implemented currently. Any attempts 
to use these functions will result in a compile-time error message. However they are de- 
scribed at the end of this chapter. 


BOOLEAN-OF-INTEGER 
CHAR-NATIONAL 
DISPLAY-OF 
EXCEPTION-FILE-N 
EXCEPTION-LOCATION-N 
INTEGER-OF-BOOLEAN 
NATIONAL-OF 
STANDARD-COMPARE 


The supported intrinsic functions are listed in the following sections, along with their 
syntax and usage notes. 
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8.1.1. ABS 


( ABS Function Syntax 


ABS (number) 


This function determines and returns the absolute value of number (a numeric literal or 
data item) supplied as an argument. 


Note that ABSOLUTE-VALUE has an alias for this function. 
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8.1.2. ACOS 


( ACOS Function Syntax } 


ACOS (cosine) 


The ACOS function determines and returns the trigonometric arc-cosine, or inverse cosine, 
of cosine value (a numeric literal or data item) supplied as an argument. 


The result will be an angle, expressed in radians. You may convert this to an angle 
measured in degrees, as follows: 


COMPUTE degrees = ( radians * 180 ) / FUNCTION PI 
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8.1.3. ANNUITY 


( ANNUITY Function Syntax 


ANNUITY (interest-rate, number-of-periods) 


This function returns a numeric value approximating the ratio of an annuity paid at interest- 
rate (numeric data item or literal) for each of number-of-periods (numeric data items or 
literals). 

interest-rate is the rate of interest paid at each payment. If you only have an annual 
interest rate and you wish to compute monthly annuity payments, divide the annual interest 
rate by 12 and use that value for interest-rate. 

Multiply the result of this function times the desired principal amount to determine the 
amount of each period’s payment. 

A note for the financially challenged: an annuity is basically a reverse loan; an accountant 
would take the result of this function multiplied by -1 times the principal amount to compute 
a loan payment you are making. 
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8.1.4. ASIN 


( ASIN Function Syntax } 


ASIN(sine) 


The ASIN function determines and returns the trigonometric arc-sine, or inverse sine, of 
sine value (a numeric literal or data item) supplied as an argument. 


The result will be an angle, expressed in radians. You may convert this to an angle 
measured in degrees, as follows: 


COMPUTE degrees = ( radians * 180 ) / FUNCTION PI 
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8.1.5. ATAN 


( ATAN Function Syntax 


ATAN (tangent ) 


Use this function to determine and return the trigonometric arc-tangent, or inverse tangent, 
of tangent value (a numeric literal or data item) supplied as an argument. 


The result will be an angle, expressed in radians. You may convert this to an angle 
measured in degrees, as follows: 


COMPUTE degrees = ( radians * 180 ) / FUNCTION PI 
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8.1.6. BIT-OF 


( BIT-OF Function Syntax ] 


BIT-OF (argument-1) 


BIT-OF function returns an alphanumeric character string of ’1’ and ’0’ characters, which 
represents the binary value of each byte in the argument used on input. 


1. The function type is alphanumeric. 
2. argument-1 must be a data item, literal, or an intrinsic function result of any data 
class. 
Returned values: 


1. An alphanumeric character string consisting of the binary representation of each byte 
in argument-1. 


2. The length of the character string returned, in bytes, is eight times the length of 
argument-1, in bytes. 
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8.1.7. BIT-TO-CHAR 


[ 


BIT-TO-CHAR Function Syntax 


BIT-TO-CHAR {argument-1) 


BIT-TO-CHAR function returns a character string that represents a bit pattern supplied on 


input. 
1. The function type is alphanumeric. 
2. argument-1 must be an alphanumeric literal, alphanumeric data item, or alphanumeric 
group item. 
3. argument-1 must consist only of the characters ’0’ and ’1’. 
4. The length of argument-1 must be a multiple of 8 bytes. 


Returned values: 


1. 


2. 


A character string consisting of bytes representing the sequence of ’0’ and ’1’ characters 
in argument-1. 


The length of the result string is equal to the length of the input string divided by 8. 
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8.1.8. BYTE-LENGTH 


( BYTE-LENGTH Function Syntax 


BYTE-LENGTH (string) 


BYTE-LENGTH returns the length — in bytes — of string (a group item, USAGE DISPLAY ele- 
mentary item or alphanumeric literal). This intrinsic function is identical to the LENGTH-AN 
(see [LENGTH-AN], page 466) function. Note that the value returned by this function is 
not necessarily the number of characters comprising string, but rather the number of actual 
bytes required to store it. 

For example, if string is encoded using a double-byte character set such as Unicode 
UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent 
to character sets like ASCII or EBCDIC), then calling this function with a string argument 
whose PICTURE (see [PICTURE], page 194) is N(4) would return a value of 8 rather than 
the value 4. 


Contrast this with the LENGTH (see [LENGTH], page 465) function. 
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8.1.9. CHAR 


( CHAR Function Syntax 


CHAR (integer) 


This function returns the character in the ordinal position specified by integer (a numeric 
integer literal or data item with a value of 1 or greater) from the COLLATING SEQUENCE (see 
[OBJECT-COMPUTER], page 90) being used by the program. 


For example, if the program is using the (default) ASCII character set, CHAR(34) 
returns the 34th character in the ASCII character set — an exclamation-point (‘!’). If you 
are using this function to convert a numeric value to its corresponding ASCII character, 
you must use an argument value one greater than the numeric value. 


If an argument whose value is less than 1 or greater than 256 is specified, the character 
in the program collating sequence corresponding to a value of all zero bits is returned. 


The following code is an alternative approach when you just wish to convert a number 
to its ASCII equivalent: 


O01 Char-Value. 
05 Numeric-Value USAGE BINARY-CHAR. 


MOVE numeric-character-value TO Numeric-Value 


The Char-Value item now has the corresponding ASCII character value. 
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8.1.10. COMBINED-DATETIME 


( COMBINED-DATETIME Function Syntax 


COMBINED-DATETIME(days, seconds) 


This function returns a 12-digit numeric result, the first seven digits of which are the integer 
value of days argument (a numeric data item or literal) and the last five of which are the 
integer value of seconds argument (also a numeric data item or literal). 


If days is less than 1 or greater than 3,067,671, or if seconds is less than 1 or greater 
than 86,400, a value of 0 is returned and a runtime error will result. 


days Must be in integer date form. For details, see Integer date form. A value in integer 
date form is a positive integer that represents a number of days succeeding 31 December 
1600, in the Gregorian calendar. It is based on a starting date of Monday, 1 January 1601 
and integer date 1 represents Monday, 1 January 1601. 


seconds Must be in standard numeric time form. For details, see Standard numeric time 
form. A value in standard numeric time form is a numeric value representing seconds past 
midnight. 

The returned value is determined by arithmetic expression Days-1 + (Seconds-2/100000). 
The date occupies the integer part of the returned value and the time is represented in the 
fractional part of the returned value. 

Example Given the integer date form value "143951", which represents the date 
15 February 1995, and the standard numeric time form value "18867.812479168304", 
which represents the time "05:14:27.812479168304", the returned value would be exactly 
"143951.1886781247". 
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8.1.11. CONCAT 


( CONCAT Function Syntax 


CONCAT | CONCATENATE (argument-1 [, argument-2 ]...) 


This function concatenates the argument-1, argument-2, ... (group items, USAGE DISPLAY 
elementary items and/or alphanumeric literals) together into a single string result. 


If a numeric literal or PIC 9 identifier is specified as an argument, decimal points, if any, 
will be removed and negative signs in PIC SQ fields or numeric literals will be inserted as 
defined by the SIGN IS (see [SIGN IS], page 213) clause (or absence thereof) of the field. 
Numeric literals are processed as if SIGN IS TRAILING SEPARATE were in effect. 
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8.1.11. CONCATENATE 


( CONCATENATE Function Syntax 


CONCAT | CONCATENATE (argument-1 [, argument-2 ]...) 


This function concatenates the string-1, string-2, ... (group items, USAGE DISPLAY elemen- 
tary items and/or alphanumeric literals) together into a single string result. 

If a numeric literal or PIC 9 identifier is specified as an argument, decimal points, if any, 
will be removed and negative signs in PIC SQ fields or numeric literals will be inserted as 
defined by the SIGN IS (see [SIGN IS], page 213) clause (or absence thereof) of the field. 
Numeric literals are processed as if SIGN IS TRAILING SEPARATE were in effect. 

CONCATENATE is a GnuCOBOL extention BUT also see the ISO standard CONCAT 
function. 
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8.1.12. CONTENT-LENGTH 


( CONTENT-LENGTH Function Syntax 


CONTENT-LENGTH argument-1 


Scans for a NUL byte delimiter of the data starting at address in given pointer, and returns 
the length. The NUL byte is not included in the count. An EC-DATA-PTR-NUL exception 
is set to exist if the pointer is NUL, and a zero length is returned. 


Function CONTENT-LENGTH is a GnuCOBOL extention. 


Example: 


01 ptr USAGE POINTER. 
01 str PIC X(4) VALUE z"abc". 


SET ptr TO ADDESS OF str. 
DISPLAY FUNCTION CONTENT-LENGTH (str). 


Will display 3. 
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8.1.13. CONTENT-OF 


( CONTENT-OF Function Syntax } 


CONTENT-OF pointer-1 { length } 


Takes a pointer and optional length. Returns a character field of the data addressed by the 
pointer, either up to a NUL byte or to the given length. 


The NUL byte is not included in the data when no optional length is given. With an 
optional count, the character field can hold any content including NUL bytes, 


An EC-DATA-PTR-NUL exception is set to exist if the pointer is NUL, and a zero length 
space is returned. 


An EC-SIZE-TRANCATION is set if the resulting field would exceed character field 
limits and the data is truncated. 


Reference modification is allowed on resulting field. 
Function CONTENT-OF is a GnuCOBOL extention. 
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8.1.14. COS 


( COS Function Syntax 


COS (angle) 


The COS function determines and returns the trigonometric cosine of angle (a numeric literal 
or data item) supplied as an argument. 


angle is assumed to be a value expressed in radians. If you need to determine the cosine 
of an angle measured in degrees, you first need to convert that angle to radians as follows: 


COMPUTE radians = ( degrees * FUNCTION PI) / 180 
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8.1.15. CURRENCY-SYMBOL 


( CURRENCY-SYMBOL Function Syntax 


CURRENCY-SYMBOL 


The CURRENCY-SYMBOL function returns the currency symbol character currently in effect 
for the locale under which your program is running. On UNIX systems, your locale is 
established via the LANG run-time environment variable (see [Run Time Environment 
Variables], page 654) environment variable. On Windows, the Control Panel’s "Regional 
and Language Options" define the locale. 


Changing the currency symbol via the SPECIAL-NAMES (see [SPECIAL-NAMES], 
page 92) paragraph’s CURRENCY SYMBOL setting will not affect the value returned by this 
function. 
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8.1.16. CURRENT-DATE 


( CURRENT-DATE Function Syntax 


CURRENT-DATE 


Returns the current date and time as the following 21-character structure: 
O01 CURRENT-DATE-AND-TIME. 


05 CDT-Year PIC 9(4). 

05 CDT-Month PIC 9(2). *> 01-12 
05 CDT-Day PIC 9(2). *> 01-31 
05 CDT-Hour PIC 9(2). *> 00-23 
05 CDT-Minutes PIC 9(2). *> 00-59 
05 CDT-Seconds PIC 9(2). *> 00-59 
05 CDT-Hundredths-Of-Secs PIC 9(2). *> 00-99 
05 CDT-GMT-Diff-Hours PIC S9(2) 


SIGN LEADING SEPARATE. 
05 CDT-GMT-Diff-Minutes PIC 9(2). *> 00 or 30 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.17. DATE-OF-INTEGER 


( DATE-OF-INTEGER Function Syntax } 


DATE-OF-INTEGER (integer) 


This function returns a numeric calendar date in yyyymmdd (i.e. Gregorian) format. The 
date is determined by adding the number of days specified as integer (a numeric integer 
data item or literal) to the date December 31, 1600. For example, DATE-OF-INTEGER (1) 
returns 16010101 while DATE-OF-INTEGER (150000) returns 20110908. 


A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0. 
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8.1.18. DATE-TO-YYYYMMDD 


( DATE-TO-YYYYMMDD Function Syntax 


DATE-TO-YYYYMMDD(yymmdd [, yy-cutoff [, yy-execution-time ]]) 


You can use this function to convert the six-digit Gregorian date specified as yymmdd (a 
numeric integer data item or literal) to an eight-digit format (yyyymmdd). 


The optional yy-cutoff (a numeric integer data item or literal) argument is the year 
cutoff used to delineate centuries; if the year component of the date meets or exceeds this 
cutoff value, the result will be 19yymmdd; if the year component of the date is less than the 
cutoff value, the result will be 20yymmdd. The default cutoff value if no second argument 
is given will be 50. 


The optional yy-execution-time argument (a numeric integer data item or literal) The 
default execution time value if no third argument is given will be now equivalent to specifying 
(FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))). 
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8.1.19. DAY-OF-INTEGER 


f DAY-OF-INTEGER Function Syntax } 


DAY-OF-INTEGER (integer) 


This function returns a calendar date in yyyyddd (i.e. Julian) format. The date is de- 
termined by adding the number of days specified as integer (a numeric integer data item 
or literal) to December 31, 1600. For example, DAY-OF-INTEGER(1) returns 1601001 while 
DAY-OF-INTEGER (250000) returns 2011251. 


A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0. 
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8.1.20. DAY-TO-YYYYDDD 


( DAY-TO-YYYYDDD Function Syntax 


DAY-TO-YYYYDDD(yyddd [, yy-cutoff [, yy-execution-time ]]) 


You can use this function to convert the five-digit Julian date specified as yyddd (a numeric 
integer data item or literal) to a seven-digit numeric Julian format (yyyyddd). 


The optional yy-cutoff argument (a numeric integer data item or literal) is the year 
cutoff used to delineate centuries; if the year component of the date meets or exceeds this 
cutoff value, the result will be 19yyddd; if the year component of the date is less than the 
cutoff, the result will be 20yyddd. The default cutoff value if no second argument is given 
will be 50. 


The optional yy-execution-time argument (a numeric integer data item or literal) The 
default execution time value if no third argument is given will be now equivalent to specifying 
(FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))). 
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8.1.21. E 


( E Function Syntax 


This function returns the mathematical constant E (the base of natural log- 
arithms). The maximum precision with which this value may be returned is 
2.71828182845904523536028747 13526625. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.22. EXCEPTION-FILE 


( EXCEPTION-FILE Function Syntax 


EXCEPTION-FILE 


This function returns I/O exception information from the most-recently executed input or 
output statement. The information is returned as a 34-character string, where the first 
two characters are the two-digit file status value (see [File Status Codes], page 107) and 
the remaining 32 are the file-name-1 specification from the file’s SELECT (see [SELECT], 
page 104) statement. 

The name returned after the file status information will be returned only if the returned 
file status value is not 00. 


Since this function has no arguments, no parenthesis should be specified. 


The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 
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8.1.23. EXCEPTION-LOCATION 


( EXCEPTION-LOCATION Function Syntax } 


EXCEPTION-LOCATION 


This function returns exception information from the most-recently failing statement. The 
information is returned to a 1023 character string in one of the following formats, depending 
on the nature of the failure: 


e primary-entry-point-name; paragraph OF section; statement-number 
e primary-entry-point-name; section; statement-number 
e primary-entry-point-name; paragraph; statement-number 


e primary-entry-point-name; statement-number 


Since this function has no arguments, no parenthesis should be specified. 


The program must be compiled with the -debug switch, -ftraceall switch or -g 
switch for this function to return any meaningful information. 


The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 
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8.1.24. EXCEPTION-STATEMENT 


( EXCEPTION-STATEMENT Function Syntax 


EXCEPTION-STATEMENT 


This function returns the most-recent COBOL statement that generated an exception con- 
dition. 
Since this function has no arguments, no parenthesis should be specified. 


The program must be compiled with the -debug switch, -ftraceall switch or -g 
switch for this function to return any meaningful information. 


The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 
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8.1.25. EXCEPTION-STATUS 


( EXCEPTION-STATUS Function Syntax } 


EXCEPTION-STATUS 


This function returns the error type (a text string — see column 2 of the upcoming table for 
the possible values) from the most-recent COBOL statement that generated an exception 
condition. 

Since this function has no arguments, no parenthesis should be specified. 

The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 

The following are the error type strings, and their corresponding exception codes and 
descriptions. 


Code Error Type Description 


0101 EC-ARGUMENT-FUNCTION Function argument error 


OCCURS ... DEPENDING ON data item out of 
bounds 


0202 EC-BOUND-ODO 


0204 EC-BOUND-PTR Data-pointer contains an address that is out of 


bounds 
0205 EC-BOUND-REF-MOD Reference modifier out of bounds 


0207 EC-BOUND-SUBSCRIPT Subscript out of bounds 


0303 EC-DATA-INCOMPATIBLE Incompatible data exception 

0500 EC-I-O input-output exception 

0501 EC-I-0-AT-END I-O status 1x 

0502 EC-I-0O-E0P An end of page condition occurred 
0504 EC-I-0-FILE-SHARING LO status 6x 

0505 EC-I-O-IMP I-O status 9x 

0506 EC-I-O-INVALID-KEY I-O status 2x 
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0508 EC-I-O-LOGIC-ERROR LO status 4x 
0509 EC-I-O-PERMANENT-ERROR LO status 3x 


O5S0A EC-I-O-RECORD-OPERATION LO status 5x 


0601 EC-IMP-ACCEPT Implementation-defined accept condition 
0602 EC-IMP-DISPLAY Implementation-defined display condition 
OA00 EC-OVERFLOW Overflow condition 

OA02 EC-OVERFLOW-STRING STRING overflow condition 

0A03 EC-OVERFLOW-UNSTRING UNSTRING overflow condition 

OBO5 EC-PROGRAM-NOT-FOUND Called program not found 

0ODO3 EC-RANGE-INSPECT-SIZE Size of replace item in inspect differs 
1000 EC-SIZE Size error exception 

1004 EC-SIZE-OVERFLOW Arithmetic overflow in calculation 

1005 EC-SIZE-TRUNCATION Significant digits truncated in store 

1007 EC-SIZE-ZERO-DIVIDE Division by zero 

1202 EC-STORAGE-NOT-ALLOC The data-pointer specified in a FREE statement 


does not identify currently allocated storage 


1203 EC-STORAGE-NOT-AVAIL The amount of storage requested by an 
ALLOCATE statement is not available 
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8.1.26. EXP 


( EXP Function Syntax ] 


EXP (number) 


Computes and returns the value of the mathematical constant e raised to the power specified 
by number (a numeric literal or data item). 
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8.1.27. EXP10 


( EXP10 Function Syntax 


EXP10 (number) 


Computes and returns the value of 10 raised to the power specified by number (a numeric 
literal or data item). 
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8.1.28. FACTORIAL 


( FACTORIAL Function Syntax } 


FACTORIAL (number) 


This function computes and returns the factorial value of number (a numeric literal or data 
item). 
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8.1.29. FORMATTED-CURRENT-DATE 


f FORMATTED-CURRENT-DATE Function Syntax 


FORMATTED-CURRENT-DATE ( argument-1 ) 


FORMATTED-CURRENT-DATE returns the current date and time provided by the system at 
run-time, formatted according to date-and-time-format according to the argument type. 


FUNCTION FORMATTED-CURRENT-DATE gives you exactly what you asked it to, 
including up to nanoseconds (8 decimal positions in the seconds) [but the system may only 
provide miliseconds, especially on older win32]. 


The function argument must be a national or alphanumeric literal and the content, a 
combined date and time format. 


The returned value is formatted to the same form as argument-1. 
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8.1.30. FORMATTED-DATE 


f FORMATTED-DATE Function Syntax } 


FORMATTED-DATE ( argument-1, argument-2 ) 


FORMATTED-DATE uses a format to convert a date in integer date form to a date in the 
requested format. The returned value will be in date format. 


argument-1 shall be a national or alphanumeric literal. 


argument-2 shall be a value in integer date form. 
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8.1.31. FORMATTED-DATETIME 


f FORMATTED-DATETIME Function Syntax 


FORMATTED-DATETIME ( argument-1, argument-2, argument-3, argument-4 ) 


FORMATTED-DATETIME uses a combined time and date form to convert and combine a date 
in integer form and a numeric time expressed as seconds past midnight in UTC. 


argument-1 shall be a national or alphanumeric literal. 
argument-2 shall be a value in integer date form. 
argument-3 shall be a value in standard numeric time form. 


argument-4 is an integer specifying the offset from UTC expressed in minutes. If specified 
but have a value equal or less than 1439. 

Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less 
than a day. 

argument-4 must not be specified if the time portion in argument-1 is neither a UTC 
nor an offset format. 

The returned value is a representation of the date contained in argument-2 combined 
with the time contained in argument-3 according to the format in argument-1. 

If the format in argument-1 indicates that the returned value is to be expressed in UTC, 
the time portion of the returned value reflects the adjustment of the value in argument-3 
by the offset in argument-4. 

If the format in argument-1 indicates that the time is to be returned as an offset from 
UTC, the value in argument-3 is reflected directly in the time portion of the returned value 
and the offset in argument-4 is reflected directly in the offset portion of the returned value. 
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8.1.32. FORMATTED-TIME 


f FORMATTED-TIME Function Syntax 


FORMATTED-TIME ( argument-1, argument-2, argument-3 ) 


FORMATTED-TIME converts a value representing seconds past midnight formatted time of day 
with optional offset. 


argument-1 shall be a national or alphanumeric literal. 

argument-2 shall be a value in integer time form. 

argument-3 is an integer specifying the offset from UTC expressed in minutes. If specified 
but have a value equal or less than 1439. 

Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less 
than a day. 

argument-3 must not be specified if the time portion in argument-1 is neither a UTC 
nor an offset format. 

Returned value : 

Is a representation of the standard numeric time contained in argument-2 according to 
the format in argument-1. 

If the format in argument-1 indicates that the returned value is to be expressed in UTC, 
the time portion of the returned value reflects the adjustment of the value in argument-2 
by the offset in argument-3. 

If the format in argument-1 indicates that the time is to be returned as an offset from 
UTC, the value in argument-2 is reflected directly in the time portion of the returned value 
and the offset in argument-3 is reflected directly in the offset portion of the returned value. 


15 January 2023 Chapter 8 - Functions 


456 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


8.1.33. FRACTION-PART 


( FRACTION-PART Function Syntax 


FRACTION-PART (number ) 


This function returns that portion of number (a numeric data item or a numeric literal) that 
occurs to the right of the decimal point. FRACTION-PART (3.1415), for example, returns a 
value of 0.1415. This function is equivalent to the expression: 


number -- FUNCTION INTEGER-PART (number) 


Example: 

display "base - " FUNCTION FRACTION-PART(FLOATER) . 
Gives 

base - 000.456789 


1. When moved to a variable, it MUST have a preceding ’V’ in the PICTURE, i.e., PIC 
v(4). 
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8.1.34. HEX-OF 


f HEX-OF Function Syntax j 


HEX-OF {argument-1) 


HEX-OF function returns an alphanumeric character string consisting of a hexadecimal rep- 
resentation of the argument used on input. 


1. The type of the function is alphanumeric. 
2. argument-1 must be a data item, literal, or an intrinsic function result of any data 
class. 
Returned values: 


1. An alphanumeric character string consisting of a hexadecimal representation of 
argument-1. 


2. The length of the character string returned, in bytes, is twice the length of argument-1, 
in bytes. 
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8.1.35. HEX-TO-CHAR 


( HEX-TO-CHAR Function Syntax } 


HEX-TO-CHAR {argument-1) 


HEX-TO-CHAR function returns a character string that represents the hexadecimal digit char- 
acters supplied on input. 


1. The type of the function is alphanumeric. 

2. argument-1 must be an alphanumeric literal, alphanumeric data item, or alphanumeric 
group item. 

3. argument-1 must consist only of the characters ’0’ through ’9’, ’A’ through ’F’, and ’a’ 
through ’f’. 

4. The length of argument-1 must be a multiple of 2 bytes. 

Returned values: 
1. A character string of bytes representing the hexadecimal digit characters of argument-1. 


2. The length of the result string is equal to the length of the input string divided by 2. 
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8.1.36. HIGHEST-ALGEBRAIC 


f HIGHEST-ALGEBRAIC Function Syntax } 


HIGHEST-ALGEBRAIC (numeric-identifier) 


This function returns the highest (i.e. largest or farthest away from 0 in a positive direction 
if numeric-identifier is signed) value that could possibly be stored in numeric-identifier. 
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8.1.37. INTEGER 


( INTEGER Function Syntax 


INTEGER (number) 


The INTEGER function returns the greatest integer value that is less than or equal to number 
(a numeric literal or data item). 
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8.1.38. INTEGER-OF-DATE 


( INTEGER-OF-DATE Function Syntax } 


INTEGER-OF-DATE (date) 


This function converts date (a numeric integer data item or literal) — presumed to be 
a Gregorian calendar form standard date (YYYYMMDD) — to internal date form (the 
number of days that have transpired since 1600/12/31). 

Once in that form, mathematical operations may be performed against the internal 
date before it is transformed back into a date using the DATE-OF-INTEGER (see [DATE-OF- 
INTEGER], page 439) or DAY-OF-INTEGER (see [DAY-OF-INTEGER], page 441) function. 
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8.1.39. INTEGER-OF-DAY 


( INTEGER-OF-DAY Function Syntax } 


INTEGER-OF-DAY (date) 


This function converts date (a numeric integer data item or literal) — presumed to be a 
Julian calendar form standard date (YYYYDDD) — to internal date form (the number of 
days that have transpired since 1600/12/31). 


Once in that form, mathematical operations may be performed against the internal 
date before it is transformed back into a date using the DATE-OF-INTEGER (see [DATE-OF- 
INTEGER], page 439) or DAY-OF-INTEGER (see [DAY-OF-INTEGER], page 441) function. 
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8.1.40. INTEGER-OF-FORMATTED-DATE 


( INTEGER-OF-FORMATTED-DATE Function Syntax } 


INTEGER-OF-FORMATTED-DATE ( argument-1, argument-2 ) 


INTEGER-OF-FORMATTED-DATE converts a date that is in specified format to integer date 
form. 


argument-1 shall be a national or alphanumeric literal. The content must be either a 
date format or a combined date and time format. 


argument-2 shall be a data item of the same type as argument-1. 


If argument-1 is a date format the content of argument-2 shall be a valid date in that 
format. 


If argument-1 is a combined date and time format, the content of argument-2 shall be 
a valid combined date and time in same format. 
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8.1.41. INTEGER-PART 


( INTEGER-PART Function Syntax 


INTEGER-PART (number) 


Returns the integer portion of number (a numeric literal or data item). 
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8.1.42. LENGTH 


( LENGTH Function Syntax } 


LENGTH (string) 


Returns the length — in characters — of string (a group item, USAGE DISPLAY elementary 
item or alphanumeric literal). 


The value returned by this function is not the number of bytes of storage occupied by 
string, but rather the number of actual characters making up the string. For example, if 
string is encoded using a double-byte character set such as Unicode UTF-16 (where each 
character is represented by 16 bits of storage, not the 8-bits inherent to character sets like 
ASCII or EBCDIC), then calling this function with a string argument whose PICTURE 
is X(4) would return a value of 4 rather than the value 8 (the actual number of bytes of 
storage occupied by that item). 


Contrast this function with the BYTE-LENGTH (see [BYTE-LENGTH], page 429) and 
LENGTH-AN (see [LENGTH-AN], page 466) functions. 
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8.1.43. LENGTH-AN 


( LENGTH-AN Function Syntax } 


LENGTH-AN (string) 


This function returns the length — in bytes of storage — of string (a group item, USAGE 
DISPLAY elementary item or alphanumeric literal). 

This intrinsic function is identical to the BYTE-LENGTH (see [BY TE-LENGTH], page 429) 
function. 

Note that the value returned by this function is not the number of characters making 
up the string, but rather the number of actual bytes of storage required to store string. 
For example, if string is encoded using a double-byte character set such as Unicode UTF- 
16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to 
character sets like ASCII or EBCDIC), then calling this function with a string argument 
whose PICTURE is N(4) would return a value of 8 rather than the value 4. 


Contrast this with the LENGTH (see [LENGTH], page 465) function. 
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8.1.44. LOCALE-COMPARE 


( LOCALE-COMPARE Function Syntax } 


LOCALE-COMPARE(argument-1, argument-2 [ , locale ]) 


The LOCALE-COMPARE function returns a character indicating the result of comparing 
argument-1 and argument-2 using a culturally-preferred ordering defined by a locale. 


Either or both of the 18* two arguments may be an alphanumeric literal, a group item or 
an elementary item appropriate to storing alphabetic or alphanumeric data. If the lengths 
of the two arguments are unequal, the shorter will be assumed to be padded to the right 
with spaces. 


The two arguments will be compared, character by character, against each other until 
their relationship to each other can be determined. The comparison is made according to 
the cultural rules in effect for locale name or for the current locale if no locale argument is 
specified. Once that relationship is determined, a one-character alphanumeric value will be 
returned as follows: 


e ‘<’ — If argument-1 is determined to be less than argument-2 
e ‘=’ — If the two arguments are equal to each other 
e ‘>’ — If argument-1 is determined to be greater than argument-2 


See [LOCALE Names], page 93, for a list of typically-available locale names. 
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8.1.45. LOCALE-DATE 


( LOCALE-DATE Function Syntax 


LOCALE-DATE(date [, locale ]) 


Converts the eight-digit Gregorian date (a numeric integer data item or literal) from yyyym- 
mdd format to the format appropriate to the current locale. On a Windows system, this 
will be the “short date” format as set using Control Panel. 


You may include an optional second argument to specify the locale name (group item or 
PIC X identifier) you’d like to use for date formatting. If used, this second argument must 
be an identifier. Locale names are specified using UNIX-standard names. 
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8.1.46. LOCALE-TIME 


( LOCALE-TIME Function Syntax } 


LOCALE-TIME(time [, locale ]) 


Converts the four- (hhmm) or six-digit (hhmmss) time (a numeric integer data item or 
literal) to a format appropriate to the current locale. On a Windows system, this will be 
the “time” format as set using Control Panel. 

You may include an optional locale name (a group item or PIC X identifier) you’d like to 
use for time formatting. If used, this second argument must be an identifier. Locale names 
are specified using UNIX-standard names. 
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8.1.47. LOCALE-TIME-FROM-SECONDS 


( LOCALE-TIME-FROM-SECONDS Function Syntax 


LOCALE-TIME-FROM-SECONDS (seconds [, locale ]) 


Converts the number of seconds since midnight (a numeric integer data item or literal) to 
a format appropriate to the current locale. On a Windows system, this will be the “time” 
format as set using Control Panel. 

You may include an optional locale name (a group item or PIC X identifier) you’d like to 
use for time formatting. If used, this second argument must be an identifier. Locale names 
are specified using UNIX-standard names. 


See [LOCALE Names], page 93, for a list of typically-available locale names. 
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8.1.48. LOG 


( LOG Function Syntax } 


LOG (number) 


Computes and returns the natural logarithm (base e) of number (a numeric literal or data 
item). 
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8.1.49. LOG10 


( LOG10 Function Syntax 


LOG10 (number) 


Computes and returns the base 10 logarithm of number (a numeric literal or data item). 
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8.1.50. LOWER-CASE 


( LOWER-CASE Function Syntax } 


LOWER-CASE (string) 


This function returns the value of string (a group item, USAGE DISPLAY elementary item or 
alphanumeric literal), converted entirely to lower case. 


What constitutes a “letter” (or upper/lower case too, for that manner) may be influenced 
through the use of a CHARACTER CLASSIFICATION (see [OBJECT-COMPUTER], page 90). 
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8.1.51. LOWEST-ALGEBRAIC 


( LOWEST-ALGEBRAIC Function Syntax 


LOWEST-ALGEBRAIC (numeric-identifier) 


This function returns the lowest (i.e. smallest or farthest away from 0 in a negative direction 
if numeric-identifier is signed) value that could possibly be stored in numeric-identifier. 
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8.1.52. MAX 


( MAX Function Syntax } 


MAX(number-1 [, number-2 ]...) 


This function returns the maximum value from the specified list of numbers (each number-n 
may be a numeric data item or a numeric literal). 
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8.1.53. MEAN 


( MEAN Function Syntax 


MEAN(number-1 [, number-2 ]...) 


This function returns the statistical mean value of the specified list of numbers (each 
number-n may be a numeric data item or a numeric literal). 
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8.1.54. MEDIAN 


( MEDIAN Function Syntax } 


MEDIAN(number-1 [, number-2 ]...) 


This function returns the statistical median value of the specified list of numbers (each 
number-n may be a numeric data item or a numeric literal). 
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8.1.55. MIDRANGE 


( MIDRANGE Function Syntax 


MIDRANGE(number-1 [, number-2 ]...) 


The MIDRANGE (middle range) function returns a numeric value that is the arithmetic mean 
(average) of the values of the minimum and maximum numbers from the supplied list. Each 
number-n may be a numeric data items or a numeric literal. 
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8.1.56. MIN 


( MIN Function Syntax } 


MIN(number-1 [, number-2 ]...) 


This function returns the minimum value from the specified list of numbers (each number-n 
may be a numeric data item or a numeric literal). 
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8.1.57. MOD 


( MOD Function Syntax 


MOD(value, modulus) 


This function returns the value of value modulo modulus (essentially the remainder from 
the division of value by modulus). Both arguments may be numeric data items or numeric 
literals. Either (or both) may have a non-integer value. 
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8.1.58. MODULE-CALLER-ID 


( MODULE-CALLER-ID Function Syntax 


MODULE-CALLER-ID 


This function returns the null string if it is executed within a main program. When exe- 
cuted with a subprogram, it returns the entry-point name of the program that called the 
subprogram. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.59. MODULE-DATE 


( MODULE-DATE Function Syntax 


MODULE-DATE 


This function Returns the date the GnuCOBOL program that is executing the function was 
compiled, in the form yyyymmdd. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.60. MODULE-FORMATTED-DATE 


( MODULE-FORMATTED-DATE Function Syntax 


MODULE-FORMATTED-DATE 


This function returns the fully-formatted date and time when the program executing the 
function was compiled. The exact format of this returned string value may vary depending 
on the operating system and GnuCOBOL build type. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.61. MODULE-ID 


( MODULE-ID Function Syntax 


MODULE-ID 


This function returns the primary entry-point name (i.e. the PROGRAM-ID or FUNCTION-ID 
of the program. See [IDENTIFICATION DIVISION], page 85, for information on those 
clauses. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.62. MODULE-PATH 


( MODULE-PATH Function Syntax 


MODULE-PATH 


This function returns the full path to the executable version of this GnuCOBOL program. 
The filename component of this value will be exactly as typed on the command line, down 
to the use of upper- and lower-case letters and presence (or absence) of any extension. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.63. MODULE-SOURCE 


( MODULE-SOURCE Function Syntax 


MODULE-SOURCE 


The filename of the source code of the program (as specified on the cobc command when 
the program was compiled) is returned by this function. 


The discussion of the MODULE-TIME (see [MODULE-TIME], page 487) function includes 
a sample program that uses this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.64. MODULE-TIME 


[ 


MODULE-TIME Function Syntax 


MODULE-TIME 


This function returns the time the GnuCOBOL program was compiled, in the form hhmmss. 


Since this function has no arguments, no parenthesis should be specified. 


The following sample program uses all the MODULE- Functions: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEMOMODULE. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 


REPOSITORY. 


FUNCTION ALL INTRINSIC. 
PROCEDURE DIVISION. 


000-Main. 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 


STOP RUN 


The program produces this output when executed: 
MODULE-CALLER-ID = [] 

= [20180522] 
MODULE-FORMATTED-DATE = [May 22 2018 12:43:14] 


MODULE-DATE 


MODULE-ID = 


MODULE-TIME 


15 January 2023 


"MODULE-CALLER-ID 
"MODULE-DATE 
"MODULE-FORMATTED-DATE 
"MODULE-ID 
"MODULE-PATH 
"MODULE-SOURCE 
"MODULE-TIME 


[DEMOMODULE] 


[" 
[" 
[" 
[" 
[" 
[" 
[" 


MODULE-CALLER-ID ‘]? 
MODULE-DATE ‘]’ 
MODULE-FORMATTED-DATE ‘]? 
MODULE-ID ‘]? 

MODULE-PATH ‘]’ 
MODULE-SOURCE ‘]’ 
MODULE-TIME ‘]’ 


MODULE-PATH = [/home/vince/cobolsrc/ACAS/demomodule] 
MODULE-SOURCE = [demomodule.cbl] 
= [124314] 
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8.1.65. MONETARY-DECIMAL-POINT 


( MONETARY-DECIMAL-POINT Function Syntax 


MONETARY-DECIMAL-POINT 


MONETARY-DECIMAL-POINT returns the character used to separate the integer portion from 
the fractional part of a monetary currency value according to the rules currently in effect 
for the locale under which your program is running. 

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your lo- 
cale is established via the LANG run-time environment variable (see [Run Time Environment 
Variables], page 654) environment variable. On Windows, the Control Panel’s Regional and 
Language Options define the locale. 

Using the DECIMAL-POINT IS COMMA (see [SPECIAL-NAMES], page 92) clause in your 
program will not affect the value returned by this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.66. MONETARY-THOUSANDS-SEPARATOR 


( MONETARY-THOUSANDS-SEPARATOR Function Syntax 


MONETARY-THOUSANDS-SEPARATOR 


This function returns the character used to separate the thousands digit groupings of mon- 
etary currency values according to the rules currently in effect for the locale under which 
your program is running. 

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your lo- 
cale is established via the LANG run-time environment variable (see [Run Time Environment 
Variables], page 654) environment variable. On Windows, the Control Panel’s Regional and 
Language Options define the locale. 

Using the DECIMAL-POINT IS COMMA (see [SPECIAL-NAMES], page 92) clause in your 
program will not affect the value returned by this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.67. NUMERIC-DECIMAL-POINT 


( NUMERIC-DECIMAL-POINT Function Syntax 


NUMERIC-DECIMAL-POINT 


This function returns the character used to separate the integer portion of a non-integer 
numeric item from the fractional part according to the rules currently in effect for the locale 
under which your program is running. 

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your lo- 
cale is established via the LANG run-time environment variable (see [Run Time Environment 
Variables], page 654) environment variable. On Windows, the Control Panel’s Regional and 
Language Options define the locale. 

Using the DECIMAL-POINT IS COMMA (see [SPECIAL-NAMES], page 92) clause in your 
program will not affect the value returned by this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.68. NUMERIC-THOUSANDS-SEPARATOR 


( NUMERIC-THOUSANDS-SEPARATOR Function Syntax 


NUMERIC-THOUSANDS-SEPARATOR 


This function returns the character used to separate the thousands digit groupings of nu- 
meric values according to the rules currently in effect for the locale under which your 
program is running. 

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your lo- 
cale is established via the LANG run-time environment variable (see [Run Time Environment 
Variables], page 654) environment variable. On Windows, the Control Panel’s Regional and 
Language Options define the locale. 

Using the DECIMAL-POINT IS COMMA (see [SPECIAL-NAMES], page 92) clause in your 
program will not affect the value returned by this function. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.69. NUMVAL 


f NUMVAL Function Syntax } 


NUMVAL (string) 


The NUMVAL function converts a string (a group item, USAGE DISPLAY elementary item or 
alphanumeric literal) to its corresponding numeric value. 


The string must have any of the following formats, where ’#’ represents a sequence of 
one or more decimal digits: 
# # +# # #+ #CR #DB 
bo ty zy Hoy fe wey Hy : CR # : #DB 


ALOE TT TT Tas AL T° TT T° TT T 


There must be at least one digit character in the string. 
Leading and/or trailing spaces are allowed, as are spaces before the first digit. 


The character period in argument-1 string, represents the decimal separator. The char- 
acter comma in argument-1 represents the grouping separator. When the DECIMAL-POINT 
IS COMMA clause is specified, the character comma shall be used in argument-1 to represent 
the decimal separator and the character period shall be used to represent the grouping 
separator. 

Note: Locale-based functionality equivalent to NUMVAL can be obtained by using the 
NUMVAL-C function with the LOCALE keyword. A currency sign is optional in NUMVAL-C. The 
locale category LC_MONETARY will be used because there is no sign convention specified in 
locale category LC_NUMERIC. 

Returned values: 

The returned value is the numeric value represented by string. 


If it contains a CR, DB, or the minus sign (‘-’), the returned value is negative. 
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8.1.70. NUMVAL-C 


f NUMVAL-C Function Syntax 


NUMVAL-C (string [, symbol ] 


[, LOCALE locale-name-1 ] [, ANYCASE ]) 


This function converts a string (a group item, USAGE DISPLAY elementary item or alphanu- 
meric literal) representing a currency value to its corresponding numeric value. 


The currency string if any, and any grouping separators preceding the decimal separator 
are ignored. Optionally, the currency string, sign convention, grouping separator and the 
decimal separator permitted in the character string may be specified by locale category 
LC-MONETARY, or the currency string may be specified by symbol. 


The optional symbol character represents the currency symbol (a non-space single- 
character group item, USAGE DISPLAY elementary item or alphanumeric literal) that may 
be used as the currency character in string. Any spaces including leading or trailing are ig- 
nored. If no symbol is specified, the value that would be returned by the CURRENCY-SYMBOL 
intrinsic function (see [CURRENCY-SYMBOL], page 437) will be used. 


If this references the LOCALE : 


Changing the currency symbol via the SPECIAL-NAMES paragraph’s CURRENCY SYMBOL 
setting will not affect the value returned by this function. 


While NUMVAL-C will always use the currency symbol that is specified via the 
SPECIAL-NAMES paragraph’s CURRENCY SYMBOL (or the system default which is currently 
always ‘$’). 

string may have any of the following formats, where ’#’ represents a sequence of one or 
more decimal digits and ’$’ represents the symbol character: 


-# t+ d#- H+ #CR #DB 


Lf 
TT TT 


LL Fd LL L LL LL LL il LL LL LL li LL 
fH HG tHE OB ORY OCR #.44DB 
$H# -SH# +54 SH S#+ SH#CR $#DB 
SH. SHA +H SAA SHAY SHACR $4.4DB 


There must be at least one digit character in the string. 


Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency 
symbol, sign, CR and DB characters. 

If the ANYCASE keyword is used the matching rules for detecting a currency string in 
argument-1 are case-insensitive. If the ANYCASE keyword is not specified, the matching 
rules are case-sensitive. 

If neither symbol nor the LOCALE keyword is specified, there shall be only one cur- 
rency string used, either the default currency sign or a currency string specified in the 
SPECIAL-NAMES paragraph. 


The returned value is the numeric value represented by string. 
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When the LOCALE keyword is specified, the returned value is negative if string contains 
a negative sign. 


When the LOCALE keyword is not specified, the returning value is negative if string 
contains CR, DB, or a minus sign. 
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8.1.70B. NUMVAL-C-V2 


f NUMVAL-C Function Syntax 


NUMVAL-C (argument-1 [, argument-2 ] 


[, LOCALE locale-name-1 ] [, ANYCASE ]) 


This function returns the numeric value represented by the character string specified by 
argument-1 and defined as alphanumeric. 


argument-2, the currency string if any, and any grouping separators preceding the dec- 
imal separator are ignored. Optionally, the currency string, sign convention, grouping 
separator and the decimal separator permitted in the character string may be specified by 
locale category LC-MONETARY, or the currency string may be specified by argument-2. 


The optional alphanumeric argument-2 character represents the currency symbol (a non- 
space and at least one single-character item, that may be used as the currency character 
in argument-1. Any spaces including leading or trailing are ignored. If no argument-2 is 
specified, the value that would be returned by the CURRENCY-SYMBOL intrinsic function (see 
[CURRENCY-SYMBOL], page 437) will be used. argument-2 must not contain any of the 
digits - through 9, characters ‘*’, ‘+’, ‘-’, ‘,’ or ‘.’; or the two consecutive letters CR or DB, 
whether upper or lower case or a combination of both. 


argument-2 specifies a currency string that may appear in argument-1. 


If the ANYCASE keyword is specified, the matching rules for detecting a currency string 
in argument-1 are case-insensitive. If not specified, the matching rules are case-sensitive. 


If neither argument-2 nor the LOCALE keyword is specified, there shall be only one cur- 
rency string used, either the default currency sign or a currency string specified in the 
SPECIAL-NAMES paragraph. 


While NUMVAL-C will always use the currency symbol that is specified via the 
SPECIAL-NAMES paragraph’s CURRENCY SYMBOL (or the system default which is currently 
always ’$’) argument-1 shall have any of the following formats, where ’#’ represents a 
sequence of one or more decimal digits and ’$’ represents the symbol character: 

# -# +# # #+ #CR #DB 
tt RHE THEE OR OEY OF FCR O#-4#DB 
SH -S# +S# $4 S#+ SHCR S#DB 
SHH SHA tS SHH SHAY SHACR $74.744DB 


There must be at least one digit character in the string. 


Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency 
symbol, sign, CR and DB characters. 


The returned value is the numeric value represented by argument-1. 


When the LOCALE keyword is specified, the returned value is negative if string contains a 
negative sign and when not specified, the returning value is negative if string contains CR, 
DB, or a minus sign. 
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8.1.71. NUMVAL-F 


f NUMVAL-F Function Syntax 


NUMVAL-F (char) 


This function converts a string (a group item, USAGE DISPLAY elementary item or alphanu- 
meric literal) representing a floating-point value to its corresponding numeric value. 


i Ht tH FEA -HEA +#EF 
#E+ -#E+H +#E+# #E-# -#E-4# +#E-# 
HH HG tH EA -#AER +#.4EF 
#HAE+H -#.AEtH +#.#E+H #AE- -#.E-# +#.4E-F 


There must be at least one digit character both before and after the E in the string. 


Leading and/or trailing spaces are allowed, as are spaces before and/or after any sign 
characters. 
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8.1.72. ORD 


( ORD Function Syntax } 


ORD (char) 


This function returns the ordinal position in the program character set (usually ASCII) cor- 
responding to the 1*t character of char argument (a group item, USAGE DISPLAY elementary 
item or alphanumeric literal). 

For example, assuming the program is using the standard ASCII collating sequence, 
ORD(’!’) returns 34 because ‘!’ is the 34th ASCII character. If you are using this function 
to convert an ASCII character to its numeric value, you must subtract one from the result. 


The following code is an alternative approach when you just wish to convert an ASCII 
character to its numeric equivalent: 


O01 Char-Value. 
05 Numeric-Value USAGE BINARY-CHAR. 


MOVE "character" TO Char-Value 


Numeric-Value now has the numeric value of character. 
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8.1.73. ORD-MAX 


( ORD-MAX Function Syntax 


ORD-MAX(char-1 [, char-2 ]...) 


This function returns the ordinal position in the argument list corresponding to the char-n 
whose 1** character has the highest position in the program collating sequence (usually 
ASCII). 

For example, assuming the program is using the standard ASCII collating sequence, 
ORD-MAX(’?Z’, ’z’, ’!’) returns 2 because the 2nd character in the argument list (the 
ASCII character ‘z’) occurs after ‘Z’ and ‘!’ in the program collating sequence. Each 
char-n argument may be a group item, USAGE DISPLAY elementary item or alphanumeric 
literal. 
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8.1.74. ORD-MIN 


( ORD-MIN Function Syntax 


ORD-MIN(char-1 [, char-2 ]...) 


This function returns the ordinal position in the argument list corresponding to the char- 
n whose 1** character has the lowest position in the program collating sequence (usually 
ASCII). 

For example, assuming the program is using the standard ASCII collating sequence, 
ORD-MIN(’Z’, ’z’, ’!’) returns 3 because the 3rd character in the argument list (the 
ASCII character ‘!’) occurs before ‘Z’ and ‘z’ in the program collating sequence. Each 
char-n argument may be a group item, USAGE DISPLAY elementary item or alphanumeric 
literal. 
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8.1.75. PI 


( PI Function Syntax } 


PI 


This function returns the mathematical constant PI. The maximum precision with which 
this value may be returned is 3.1415926535897932384626433832795029. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.76. PRESENT-VALUE 


( PRESENT-VALUE Function Syntax } 


PRESENT-VALUE (rate, value-1 [, value-2 ]) 


The PRESENT-VALUE function returns a value that approximates the present value of a series 
of future period-end amounts specified by the various value-n arguments at a discount rate 
specified by the rate argument. 

All arguments are numeric data items and/or numeric literals. 

The following equation summarizes how present value is calculated, where N is the 


number of value arguments: 


N 
lue; 
presentvalue = y (SS) 
r 7 


i=1 
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8.1.77. RANDOM 


( RANDOM Function Syntax } 


RANDOM [ (seed) ] 


This function returns a pseudo-random non-integer value in the range 0 to 1 (for example, 
0.123456789). 


The purpose of the optional seed argument, is to initialize the chain of pseudo-random 
numbers that will be returned by the function. Not only will calls to this function using 
the same seed value return the same pseudo-random number, but so will all subsequent 
executions of the function without a seed. This is actually a good thing when you are testing 
your program because you can rely on always receiving the same sequence of “random” 
numbers if you always start using the same seed. 


The seed may be any form of literal or data item. If seed is numeric, its numeric value 
will serve as the seed value. If seed is alphanumeric, a value for it will be determined as if 
it were used as an argument to NUMVAL (see [NUMVAL], page 492). 


Take, for example, the following sample program: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEMORANDOM. 
DATA DIVISION. 

WORKING-STORAGE SECTION. 


O1 Pseudo-Random-Number USAGE COMP-1. 
PROCEDURE DIVISION. 
000-Main. 


MOVE FUNCTION RANDOM(1) TO Pseudo-Random-Number 
DISPLAY Pseudo-Random-Number 
PERFORM 4 TIMES 
MOVE FUNCTION RANDOM TO Pseudo-Random-Number 
DISPLAY Pseudo-Random-Number 
END-PERFORM 
STOP RUN 


Every time this program is executed, it will produce the same output, because the same 
sequence of pseudo-random numbers will be generated: 


0.41 
0.18467 
0.63340002 
0.26499999 
0.19169 
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It is worth mentioning that if the first execution of RANDOM in your program lacks a seed 
argument, the result will be exactly as if that execution were coded with a seed argument 
value of 1. 


Once your program has been thoroughly tested, you’ll want different sequences to be 
generated each time the program runs. One possible way to accomplish this is to use a seed 
that is likely to be different every time the program is executed, as is likely to be the case 
if the first MOVE statement in the previous example were replaced by this: 


MOVE RANDOMC(FUNCTION CURRENT-DATE(1:16) ) 
TO Pseudo-Random-Number 


The first 16 characters returned by the CURRENT-DATE (see [CURRENT-DATE], 
page 438) function will be a number in the format YYYYMMDDhhmmssnn, where YYYYMMDD 
is the current calendar date and hhmmssnn is the current time of day to the one 
one-hundredth of a second. Since two different executions of the program will never get 
identical CURRENT-DATE values (unless they are executed in extremely close time frames to 
one another), using those first sixteen characters as the RANDOM seed will guarantee that 
receiving a duplicate sequence of pseudo-random numbers in two different executions of 
the program will be highly unlikely. 
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8.1.78. RANGE 


( RANGE Function Syntax } 


RANGE(number-1 [, number-2 ]...) 


The RANGE function returns a value that is equal to the value of the maximum number-n in 
the argument list minus the value of the minimum number-n argument. 


All number-n arguments are numeric data items and/or numeric literals. 
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8.1.79. REM 


( REM Function Syntax } 


REM (number , divisor) 


This function returns a numeric value that is the remainder of number divided by divisor. 
Both arguments must be numeric data items or numeric literals. 
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8.1.80. REVERSE 


( REVERSE Function Syntax } 


REVERSE (string) 


This function returns the byte-by-byte reversed value of string (a group item, USAGE 
DISPLAY elementary item or alphanumeric literal). 
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8.1.81. SECONDS-FROM-FORMATTED-TIME 


( SECONDS-FROM-FORMATTED-TIME Function Syntax } 


SECONDS-FROM-FORMATTED-TIME (format , time) 


This function decodes the string time — whose value represents a formatted time — and 
returns the total number of seconds that string represents. 


The time string must contain hours, minutes and seconds. The time argument may be 
specified as a group item, USAGE DISPLAY elementary item or an alphanumeric literal. 


The format argument is a string (a group item, USAGE DISPLAY elementary item or 
an alphanumeric literal) documenting the format of time using hh, mm and ss to denote 
where the respective time information can be found. Any other characters found in format 
represent character positions that will be ignored. For example, a format of hhmmss indicates 
that time will be treated as a six-digit string value where the first two characters are the 
number of hours, the next two represent minutes and the last two represent seconds. A 
format of hh:mm:ss, however, describes time as an eight-character string where characters 
3 and 6 will be ignored. 
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8.1.82. SECONDS-PAST-MIDNIGHT 


( SECONDS-PAST-MIDNIGHT Function Syntax } 


SECONDS-PAST-MIDNIGHT 


This function returns the current time of day expressed as the total number of elapsed 
seconds since midnight. 


Since this function has no arguments, no parenthesis should be specified. 
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8.1.83. SIGN 


( SIGN Function Syntax } 


SIGN (number) 


The SIGN function returns a -1 if the value of number (a numeric literal or numeric data 
item) is negative, a zero if the value of number is exactly zero and a 1 if the value of number 
if greater than 0. 
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8.1.84. SIN 


( SIN Function Syntax 


SIN (angle) 


This function determines and returns the trigonometric sine of angle (a numeric literal or 
numeric data item). 


The angle is assumed to be a value expressed in radians. If you need to determine the 
sine of an angle measured in degrees, you first need to convert that angle to radians as 
follows: 


COMPUTE radians = ( degrees * FUNCTION PI) / 180 
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8.1.85. SQRT 


SQRT Function Syntax } 


SQRT (number) 


The SQRT function returns a numeric value that approximates the square root of number 
(a numeric data item or numeric literal with a non-negative value). 


The following two statements produce identical results: 
01 Result PIC 9(4).9(10). 


MOVE FUNCTION SQRT(15) TO Result 
COMPUTE Result = 15 ~ 0.5 
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8.1.86. STANDARD-DEVIATION 


( STANDARD-DEVIATION Function Syntax 


STANDARD-DEVIATION(number-1 [, number-2 ]...) 


This function returns the statistical standard deviation of the list of number-n arguments 
(numeric data items or numeric literals). 


Chapter 8 - Functions 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 513 


8.1.87. STORED-CHAR-LENGTH 


( STORED-CHAR-LENGTH Function Syntax } 


STORED-CHAR-LENGTH (string) 


Returns the length — in bytes — of the specified string (a group item, USAGE DISPLAY 
elementary item or alphanumeric literal), minus the total number of trailing spaces, if any. 
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8.1.88. SUBSTITUTE 


( SUBSTITUTE Function Syntax 


SUBSTITUTE(string, from-1, to-1 [, from-n, to-n ]...) 


This function parses string, replacing all occurrences of from-n strings with the correspond- 
ing to-n strings. 

The from-n strings must match sequences in string exactly with regard to value and 
case. 

A from-n string does not have to be the same length as its corresponding to-n string. 

All arguments are group items, USAGE DISPLAY elementary items or alphanumeric liter- 
als. 

A null to-n string will be treated as a single space. 

When using Variables in place of string attention to NOT wanting Leading or trailing 
spaces usage of function TRIM needs to be utilised as failure to do so will result in variables 
treated with any unwanted spaces leading and/or trailing, i.e., 


move function SUBSTITUTE-CASE (WS-Dest-File-Path, 
function TRIM (WS-Inbound-Path) , 
function TRIM (WS-Desc-Path) ) 
to WS-Dest-File-Path 
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8.1.89. SUBSTITUTE-CASE 


( SUBSTITUTE-CASE Function Syntax 


SUBSTITUTE-CASE(string, from-1, to-1 [, from-n, to-n ]...) 


The SUBSTITUTE-CASE function operates the same as the SUBSTITUTE (see [SUBSTITUTE], 
page 514) function, except that from-n string matching is performed without regard to case. 


All arguments are group items, USAGE DISPLAY elementary items or alphanumeric liter- 
als. 


When using Variables in place of string attention to NOT wanting Leading or trailing 
spaces usage of function TRIM needs to be utilised as failure to do so will result in variables 
treated with any unwanted spaces leading and/or trailing, i.e., 


move function SUBSTITUTE-CASE (WS-Dest-File-Path, 
function TRIM (WS-Inbound-Path) , 
function TRIM (WS-Desc-Path) ) 
to WS-Dest-File-Path 


15 January 2023 Chapter 8 - Functions 


516 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


8.1.90. SUM 


f SUM Function Syntax } 


SUM(number-1 [, number-2 ]...) 


The SUM function returns a value that is the sum of number-n arguments (these may be 
numeric data items or numeric literals). 
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8.1.91. TAN 


( TAN Function Syntax } 


TAN (angle) 


This function determines and returns the trigonometric tangent of angle (a numeric literal 
or numeric data item). 


The angle is assumed to be a value expressed in radians. If you need to determine the 
tangent of an angle measured in degrees, you first need to convert that angle to radians as 
follows: 


COMPUTE radians = ( degrees * FUNCTION PI) / 180 
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8.1.92. TEST-DATE-YYYYMMDD 


f TEST-DATE-YYYYMMDD Function Syntax 


TEST-DATE-YYYYMMDD (date) 


This function determines if the supplied date argument (a numeric integer data item or 
literal) is a valid date. 

A valid date is one of the form yyyymmdd in the range 1601/01/01 to 9999/12/31, with 
no more than the expected maximum number of days in the month, accounting for leap 
year. 

If the date is valid, a 0 value is returned. If it isn’t, a value of 1, 2 or 3 is returned 
signalling the problem lies with the year, month or day, respectively. 
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8.1.93. TEST-DAY-YYYYDDD 


f TEST-DAY-YYYYDDD Function Syntax } 


TEST-DATE-YYYYDDD (date) 


This function determines if the supplied date (a numeric integer data item or literal) is a 
valid date. 


A valid date is one of the form yyyyddd in the range 1601001 to 9999365. Leap year is 
accounted for in determining the maximum number of days in a year. 


If the date is valid, a 0 value is returned. If it isn’t, a value of 1 or 2 is returned signalling 
the problem lies with the year or day, respectively. 
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8.1.94. TEST-FORMATTED-DATETIME 


f TEST-FORMATTED-DATETIME Function Syntax } 


TEST-FORMATTED-DATETIME ( argument-1, argument-2 ) 


TEST-FORMATTED-DATETIME tests whether a date literal representing a date, a time or a 
combined date and time is valid according to the specified format. 


argument-1 shall be a national or alphanumeric literal. The content must be either a 
date format or a combined date and time format. 


argument-2 must be a data item of the same type as argument-1. 
Returned value: 


If no format or range problems occur during evaluation of argument-2 according to the 
format in argument-1, the returned value is zero. Otherwise the returned value is the ordinal 
character position at which the first error in argument-2 was detected. 
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8.1.95. TEST-NUMVAL 


f TEST-NUMVAL Function Syntax } 


TEST-NUMVAL (string) 


The TEST-NUMVAL function evaluates string (a group item, USAGE DISPLAY elementary item 
or alphanumeric literal) for being appropriate for use as the string argument to a NUMVAL 
(see [NUMVAL], page 492) function, returning to a integer a zero value if it is appropriate 
otherwise if one or more characters are in error, the position of the first character in error 
or the length of the field plus one for other cases such as all spaces. 


Note that these errors include but are not limited to: argument (string) is zero length, 
contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’. 
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8.1.96. TEST-NUMVAL-C 


f TEST-NUMVAL-C Function Syntax 


TEST-NUMVAL-C(stringL,symbol]) 


This function evaluates string (a group item, USAGE DISPLAY elementary item or alphanu- 
meric literal) for being appropriate for use as the string argument to a NUMVAL-C (see 
[NUMVAL-C], page 493) function, returning to a integer a zero value if it is appropriate 
otherwise if one or more characters are in error, the position of the first character in error 
or the length of the field plus one for other cases such as all spaces. 


Note that these errors include but are not limited to: argument (string) is zero length, 
contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’. 


The optional symbol argument serves the same function — and has the same default 
and possible values — as the corresponding argument of the NUMVAL-C function. 
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8.1.97. TEST-NUMVAL-F 


f TEST-NUMVAL-F Function Syntax 


TEST-NUMVAL-F (string) 


This function evaluates string (a group item, USAGE DISPLAY elementary item or alphanu- 
meric literal) for being appropriate for use as the string argument to a NUMVAL-F (see 
[NUMVAL-F], page 496) function, returning to a integer a zero value if it is appropriate 
otherwise if one or more characters are in error, the position of the first character in error 
or the length of the field plus one for other cases such as all spaces. 


Note that these errors include but are not limited to: argument (string) is zero length, 
contains only spaces or contains valid characters but is incomplete, such as the string ‘+.’. 
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8.1.98. TRIM 


( TRIM Function Syntax 


TRIM(string [, LEADING|TRAILING ]) 


This function removes LEADING or TRAILING spaces from string (a group item, USAGE 
DISPLAY elementary item or alphanumeric literal). 


The second argument is specified as a keyword, not a quoted string or identifier. If no 
second argument is specified, both leading and trailing spaces will be removed. The case 
(upper, lower or mixed) of this argument is irrelevant. 
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8.1.99. UPPER-CASE 


( UPPER-CASE Function Syntax } 


UPPER-CASE (string) 


This function returns the value of string (a group item, USAGE DISPLAY elementary item or 
alphanumeric literal), converted entirely to upper case. 


What constitutes a “letter” (or upper/lower case too, for that manner) may be influenced 
through the use of a CHARACTER CLASSIFICATION (see [OBJECT-COMPUTER], page 90). 
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8.1.100. VARIANCE 


( VARIANCE Function Syntax 


VARIANCE(number-1 [, number-2 ]...) 


This function returns the statistical variance of the specified list of number-n arguments 
(these may be numeric data items or numeric literals). 
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8.1.101. WHEN-COMPILED 


( WHEN-COMPILED Function Syntax ] 


WHEN-COMPILED 


The WHEN-COMPILED intrinsic function, not to be confused with the WHEN-COMPILED (see 
[Special Registers], page 265) special register, returns the date and time the program was 
compiled, in ASCII. 


Since this function has no arguments, no parenthesis should be specified. 


Unlike the WHEN-COMPILED special register, which has an ASCII value of the compilation 
date/time in the format mm/dd/yyhh.mm.ss, the WHEN-COMPILED intrinsic function returns 
the compilation date/time as an ASCII string in the format yyyymmddhhmmssnnooooo, 
where yyyymmdd is the date, hhmmss is the time, nn is the hundredths of a second component 
of the compilation time, if available (or 00 if it isn’t) and 00000 is the time zone offset from 
GMT. 

If the -fintrinsics=WHEN-COMPILED switch or -fintrinsics=ALL switch is specified 
to the compiler or the REPOSITORY (see [REPOSITORY], page 101) paragraph specifies 
either FUNCTION WHEN-COMPILED INTRINSIC or FUNCTION ALL INTRINSIC, then references 
to WHEN-COMPILED (without a leading FUNCTION keyword will always reference this intrinsic 
function and there will be no way to access the WHEN-COMPILED special register. 
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8.1.102. YEAR-TO-YYYY 


( YEAR-TO-YYYY Function Syntax 


YEAR-TO-YYYY(yy [, yy-cutoff [, yy-execution-time ]]) 


YEAR-TO-YYYY converts yy — a two-digit year — to a four-digit format (yyyy). 


The optional yy-cutoff argument is the year cutoff used to delineate centuries; if yy 
meets or exceeds this cutoff value, the result will be 19yy; if yy is less than the cutoff, the 
result will be 20yy. The default cutoff value if no second argument is given will be 50. 


The optional yy-execution-time argument (a numeric integer data item or literal) The 
default execution time value if no third argument is given will be now equivalent to specifying 
(FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))). 


All arguments must be numeric data items or numeric literals. 
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8.1.103. BOOLEAN-OF-INTEGER 


( BOOLEAN-OF-INTEGER Function Syntax } 


BOOLEAN-OF-INTEGER(argument-1 argument-2) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


BOOLEAN-OF-INTEGER returns a boolean item of usage bit representing the binary value 
of argument-1. argument-2 specifies the length of the boolean data item that is returned. 

argument-1 must be a positive integer. 

argument-2 must be a positive non-zero integer 

Returned value is a boolean item of usage bit that has the same bit configuration as 
the binary representation of the value of argument-1, where the rightmost boolean position 
is the low-order binary digit. The boolean value is zero-filled or truncated on the left, if 
necessary, in order to return a boolean item whose length is specified by argument-2 in 
therms of boolean positions. 
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8.1.104. CHAR-NATIONAL 


( CHAR-NATIONAL Function Syntax 


CHAR-NATIONAL (argument-1) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


CHAR-NATIONAL returns a one character value that is a character in the national program 
collating sequence having the ordinal position equal to the value of the argument. 


argument-1 must be a integer and greater than zero and less than or equal to the number 
of positions in the national program collating sequence. 
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8.1.105. DISPLAY-OF 


( DISPLAY-OF Function Syntax 


DISPLAY-OF (argument-1 [ argument-2] ) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


DISPLAY-OF returns a character string containing the alphabetic coded character set 
representation of the national characters in the argument. 


argument-1 must be of class national. 
argument-2 must be a of class alphabetic or alphanumeric and is one character position in 


length. It specifies an alphanumeric substitution character for use in conversion of national 
characters for which there is no corresponding alphanumeric character. 


A character string is returned with each national character of argument-1 converted to 
its corresponding alphanumeric character representation, if any. 


If argument-2 is specified, the alphanumeric substitution character is returned for each 
national character in argument-1 that has no corresponding alphanumeric character repre- 
sentation. 

If argument-2 is un-specified, and argument-1 contains a national character for which 
there is no corresponding alphanumeric character representation, an substitution character 
is used as the corresponding alphanumeric character and the EC-DATA-CONVERSION 
exception condition is set. 

The length of the returned value is the number of character positions of usage display 
required to hold the converted argument and depends on the number of characters contained 
in argument-1. 
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8.1.106. EXCEPTION-FILE-N 


( EXCEPTION-FILE-N Function Syntax 


EXCEPTION-FILE-N 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


EXCEPTION-FILE-N returns a national character string that is the I/O status value and 
file-name of the file connector, if any, associated with the last exception status. 
The value returned has a length that is based on its contents and the concents are as 
follows: 
If the last exception status is not an EC-I-O exception condition, the returned value is 
two national zeros. 
The returned value is two national spaces when the last exception status indicates an 
EC-I-0 exception condition that originates from one of the following statements: 
e a RAISE statement. 
e an EXIT or a GOBACK statement with a RAISING phrase that specifies an EC-I-0O 
exception-name. 


Otherwise the returned value is a character string that is as long as is needed to contain 
the I-O status value and the filename. The first two characters are the I-O status value in 
national characters. The succeeding characters contain the filename exactly as specified in 
the SELECT clause converted at runtime to the runtime national character set. 


The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 
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8.1.107. EXCEPTION-LOCATION-N 


( EXCEPTION-LOCATION-N Function Syntax } 


EXCEPTION-LOCATION-N 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


EXCEPTION-LOCATION-N returns an national character string containing exception infor- 
mation from the most-recently failing statement. The information is returned to a 1023 
character string in one of the following formats, depending on the nature of the failure: 


e primary-entry-point-name; paragraph OF section; statement-number 
e primary-entry-point-name; section; statement-number 
e primary-entry-point-name; paragraph; statement-number 


e primary-entry-point-name; statement-number 


Since this function has no arguments, no parenthesis should be specified. 


The program must be compiled with the -debug switch, -ftraceall switch or -g 
switch for this function to return any meaningful information. 


The documentation of the CBL_ERROR_PROC built-in system subroutine (see 
[(CBL_ERROR_PROC], page 564) built-in subroutine illustrates the use of this function. 
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8.1.108. INTEGER-OF-BOOLEAN 


( INTEGER-OF-BOOLEAN Function Syntax 


INTEGER-OF-BOOLEAN (argument-1) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


INTEGER-OF-BOOLEAN returns the numeric value of the boolean string in argument-1 
which is class boolean. 


Returned value as argument-1 is assigned to a temporary boolean data item of usage bit 
described with the same number of boolean positions. 


The unsigned binary value represented by the same bit configuration as the bit configu- 
ration of that temporary boolean data item is determined. 


Note: Binary representation is a mathematical concept. It is not required that this 
representation be the same as a COBOL representation. 
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8.1.109. NATIONAL-OF 


( NATIONAL-OF Function Syntax 


NATIONAL-OF (argument-1 [argument-2] ) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


NATIONAL-OF returns a character string containing the national character representation 
of the characters in the argument which must be of class boolean. 


A character string is returned with each alphanumeric character in argument-1 converted 
to its corresponding national coded character set representation. 


If argument-2 is specified, each character in argument-1 that has no corresponding na- 
tional representation is converted to the substitution character specified by argument-2. 


If argument-2 is unspecified and argument-1 contains an alphanumeric character for 
which there is no corresponding national character representation, a substitution character 
is used as the corresponding national character and the EC-DATA-CONVERSION exception 
condition is set to exist. 


The length of the returned value is the number of character positions of usage national 
required to hold the converted argument and depends on the number of characters contained 
in argument-1. 
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8.1.110. STANDARD-COMPARE 


( STANDARD-COMPARE Function Syntax 


STANDARD-COMPARE(argument-1 argument-2 [ordering-name-1] [argument-4] ) 


This option is not yet implemented. 
The included file NEWS will indicate when it is. 


STANDARD-COMPARE returns a character indicating the result of comparing argument-1 
as a alphanumeric and argument-2 using a cultural ordering table. 


1. argument-1 shall be of class alphabetic, alphanumeric, or national. 
argument-2 shall be of class alphabetic, alphanumeric, or national. 
argument-1 and argument-2 may be of different classes. 


Neither argument-1 nor argument-2 shall be a zero-length literal. 


St eee ah 


ordering-name-1, if specified, shall be associated with a cultural ordering table in the 
ORDER TABLE clause of the SPECIAL-NAMES paragraph. ordering-name-1 identifies the 
ordering table to be used for the comparison. If ordering-name-1 is not specified, the 
default ordering table ‘IS014651_2010-TABLE1’ described in Appendix A of ISO/IEC 
14651:2011 shall be used. 


6. argument-4, if specified, shall be a positive nonzero integer. 


Returned values: 


1. If argument-4 is unspecified, the highest level defined in the ordering table is used for 
the comparison. 


2. If the cultural ordering table is not available on the processor, or the specified ordering 
level is not available, or the level number specified by argument-4 is not defined in the 
ordering table, the EC-ORDER-NOT-SUPPORTED exception condition is set. 

3. If the arguments are of different classes, and one is national, the other argument is 
converted to class national for purposes of comparison. 

4. For purposes of comparison, trailing spaces are truncated from the operands except 
that an operand consisting of all spaces is truncated to a single space. 

5. argument-1 and argument-2 are compared in accordance with the ordering table and 

ordering level being used. 
Note: This comparison is culturally sensitive and the default ordering table is ac- 
ceptable for most cultures. It is not necessarily a character-by-character comparison 
and not necessarily a case-sensitive comparison. In order to use this function, users 
should understand the types of comparisons specified by ISO/IEC 14651:2D11 and the 
ordering tables in use for their installation. 


Chapter 8 - Functions 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 537 


6. The returned value is: 


=) 


= the arguments compare equal, 
‘6 ? 


-=.: argument-1 is less than argument-2, 


‘>? argument-1 is greater than argument-2. 
7. The length of the returned value is 1. 
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8.2. Built-In System Subroutines 


There are a number of built-in system subroutines included with GnuCOBOL. 


Generally, these routines are intended to match those available in Micro Focus COBOL, 
ACUCOBOL and directly for GnuCOBOL. 


It is recommended to change the CBL_OC routines to CBL_GC for forward compatibility 
as at some point they will be removed as they are a hangover from Open Cobol. 


Prefix explanation: 


C$ —> ACU 
CBL_ —> MF 
CBL_GC_ (For backwards compatibility some routines are also available as CBL_OC_ as 


well): but these wonderful extensions are only available with GnuCOBOL. 
These routines, all executed via their upper-case names via the CALL statement (see 
[CALL], page 293), are capable of performing the following functions: 
e Changing the current directory 
e Copying files 
e Creating a directory 
e Creating, Opening, Closing, Reading and Writing byte-stream files 
e Deleting directories (folders) 
e Deleting files 
e Determining how many arguments were passed to a subroutine 
e Getting file information (size and last-modification date/time) 
e Getting the length (in bytes) of an argument passed to a subroutine 
e Justifying a field left-, right- or center-aligned 
e Moving files (a destructive “copy” ) 
e Putting the program “to sleep”, specifying the sleep time in seconds 


e Putting the program “to sleep”, specifying the sleep time in nanoseconds; Caveat: 
although you’ll express the time in nanoseconds, Windows systems will only be able to 
sleep at a millisecond granularity 


e Retrieving information about the currently-executing program 


e Submitting a command to the shell environment appropriate for the version of Gnu- 
COBOL you are using for execution 


Early versions of Micro Focus COBOL allowed programmers to access various runtime 
library routines by using a single two-digit hexadecimal number as the entry-point name. 
These were known as call-by-number routines. Over time, Micro Focus COBOL evolved, 
replacing most of the call-by-number routines with ones accessible using a more conventional 
call-by-name technique. 


Most of the call-by-number routines have evolved into even more powerful call-by-name 
routines, many of which are supported by GnuCOBOL. 
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Some of the original call-by-number routines never evolved call-by-name equivalents; 
GnuCOBOL supports some of these routines. 

The following sections describe the various built-in subroutines. All subroutine argu- 
ments are mandatory except where explicitly noted to the contrary. Any subroutine return- 
ing a value to the RETURN-CODE special register (see [Special Registers], page 265) could 
utilize the RETURNING clause on the CALL statement to return the result back to the full-word 
binary data item of your choice. 
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8.2.1. CSCALLEDBY 


( C$CALLEDBY Built-In Subroutine Syntax 


CALL "C$CALLEDBY" USING prog-name-area 


This routine returns the name of the program that called the currently-executing program. 
The program name will be returned, left-justified and space filled, in prog-name-area argu- 
ment, which should be a PIC X elementary item or a group item. If prog-name-area is too 
small to receive the entire program name, the program name value will be truncated (on 
the right) to fit. 


The RETURN-CODE special register (see [Special Registers], page 265) will be set to one 
of the following values: 


-1 An error occurred. The prog-name-area contents will be unchanged. 

0 The program calling C$CALLEDBY was not called by any other program (in other 
words, it is a main program). The prog-name-area contents will be set entirely to 
spaces. 

1 The program calling C$CALLEDBY was indeed called by another program, and that 


program’s name has been saved in prog-name-area. 
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8.2.2. CSCHDIR 


( C$CHDIR Built-In Subroutine Syntax 


CALL "C$CHDIR" USING directory-path, result 


This routine makes directory-path (an alphanumeric literal or identifier) the current direc- 
tory. 

The return code of the operation is returned both in the result argument (any non-edited 
numeric identifier) as well as in the RETURN-CODE special register (see [Special Registers], 
page 265). The return code of the operation will be either 0=Success or 128=failure. 


The directory change remains in effect until the program terminates (in which the 
original current directory at the time the program was started will be automatically re- 
stored) or until another C$CHDIR or a CBL_CHANGE_DIR built-in system subroutine (see 
[(CBL_CHANGE_DIR], page 555) is executed. 
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8.2.3. CSCOPY 


( C$COPY Built-In Subroutine Syntax | 


CALL "C$COPY" USING src-file-path, dest-file-path, 0 


Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the cp 
(Unix/OSX) or COPY (Windows) command. 


Both file path arguments may be alphanumeric literals or identifiers. 
The third argument is required, but is unused. 


If the attempt to copy the file fails (for example, it or the destination directory doesn’t 
exist), the RETURN-CODE special register (see [Special Registers], page 265) will be set to 
128; on successful completion it will be set to 0. 
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8.2.4. CSDELETE 


( C$DELETE Built-In Subroutine Syntax } 


CALL "C$DELETE" USING file-path, 0 


This routine deletes the file specified by the file-path argument (an alphanumeric literal or 
identifier) just as if that were done using the rm (Unix/OSX) or ERASE (Windows) command. 


The second argument is required, but is unused. 


If the attempt to delete the file fails (for example, it doesn’t exist), the _RETURN-CODE 
special register (see [Special Registers], page 265) will be set to 128; on successful completion 
it will be set to 0. 
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8.2.5. C$FILEINFO 


( C$FILEINFO Built-In Subroutine Syntax 


CALL "C$FILEINFO" USING file-path, file-info 


With this routine you may retrieve the size of the file specified as the file-path argument (an 
alphanumeric literal or identifier) and the date/time that file was last modified. File size 
information may not be available in the particular GnuCOBOL build / Operating System 
combination you are using and may therefore always be returned as zero. The information 
is returned to the file-info argument, which is defined as the following 16-byte area: 


O01 File-Info. 
05 File-Size-In-Bytes PIC 9(18) COMP. 
05 Mod-YYYYMMDD PIC 9(8) COMP. *> Modification Date 
05 Mod-HHMMSSOO PIC 9(8) COMP. *> Modification Time 


The last two decimal digits in the modification time will always be 00. 


If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE special 
register (see [Special Registers], page 265). Failure to retrieve the needed statistics on the 
file will cause a RETURN-CODE special register value of 35 to be passed back. Supplying 
less than two arguments will generate a 128 RETURN-CODE special register value. 
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8.2.6. CSGETPID 


[ C$GETPID Built-In Subroutine Syntax | 


CALL "C$GETPID" 


Use this subroutine to return the PID (process ID) of the executing GnuCOBOL program. 
The PID value is returned into the RETURN-CODE special register (see [Special Registers], 
page 265). 


There are no arguments to this routine. 
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8.2.7. C$JUSTIFY 


( C$JUSTIFY Built-In Subroutine Syntax 


CALL "C$JUSTIFY" USING data-item, "justification-type" 


Use C$JUSTIFY to left, right or center-justify an alphabetic, alphanumeric or numeric edited 
data-item. The optional justification-type argument indicates the type of the justification 
to be performed. Its value is interpreted as follows: 


°C? the value will be centered 
‘R’ the value will be right-justified, space-filled to the left 
Ly the value will be left-justified, space-filled to the right 


If it begins with anything else, or is absent, it will be treated as if it is present and begins 
with a capital ‘R’ 
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8.2.8. CSMAKEDIR 


( C$MAKEDIR Built-In Subroutine Syntax 


CALL "C$MAKEDIR" USING dir-path 


With this routine you may create a new directory — the name of which is supplied as the 
dir-path argument (an alphanumeric literal or identifier). 


Only the lowest-level directory (last) in the specified path can be created — all others 
must already exist. This subroutine will not behave as a mkdir -p (Unix) or mkdir /p 
(Windows). 


The RETURN-CODE special register (see [Special Registers], page 265) will be set to the 
return code of the operation; the value will be either 0=Success or 128=failure. 
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8.2.9. CSNARG 


( C$NARG Built-In Subroutine Syntax 


CALL "C$NARG" USING arg-count-result 


This subroutine returns the number of arguments passed to the program that calls it back 
to in the numeric field arg-count-result. When called from within a user-defined function, 
a value of one (1) is returned if any arguments were passed to the function or a zero (0) 
otherwise. 


When called from a main program, the returned value will always be 0. 
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8.2.10. CSPARAMSIZE 


[ C$PARAMSIZE Built-In Subroutine Syntax } 


CALL "C$PARAMSIZE" USING argument-number 


This subroutine returns the size (in bytes) of the subroutine argument supplied using the 
argument-number parameter (a numeric literal or data item). 


The size is returned in the RETURN-CODE special register (see [Special Registers], 
page 265). 

If the specified argument does not exist, or an invalid argument number is specified, a 
value of 0 is returned. 
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8.2.11. CSPRINTABLE 


( C$PRINTABLE Built-In Subroutine Syntax 


CALL "C$PRINTABLE" USING data-item [ , char ] 


The C$PRINTABLE subroutine converts the contents of the data-item specified as the first 
argument to printable characters. Those characters that are deemed printable (as defined 
by the character set used by data-item) will remain unchanged, while those that are NOT 
printable will be converted to the character specified as the second argument. 

If no char argument is provided, a period (‘.’) will be used. 

Note: CBL_GC_PRINTABLE replaces this although it is currently still supported for 
legacy reasons. 
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8.2.12. CSSLEEP 


( C$SLEEP Built-In Subroutine Syntax } 


CALL "C$SLEEP" USING seconds-to-sleep 


C$SLEEP puts the program to sleep for the specified number of seconds and/or fractions of 
a second. The seconds-to-sleep argument may be a numeric literal or data item. 

Sleep times less than 1 will be interpreted as 0, subject to the speed of the CPU and 
the O/S (Operating System) used, as well as the timing of the generated C code, which can 
immediately returns control to the calling program without any sleep delay. 

When using a variable argument defined as 9(n)v9(m) where n is maximum seconds in 
7 days, i.e., (60 x 60 x 24 x 7) = 604,800 (seconds) and m is at a point too fast for the CPU 
and O/S. In practice m should be 2 for a hundredth of a second but actual testing against 
the target CPU would be need. 

The maximum time can be adjusted by the define MAX_SLEEP_TIME during compi- 
lation of the compiler [and no I do not know where it is in the codebase] e.g.: 


/* maximum sleep time in seconds, currently 7 days */ 
#define MAX_SLEEP_TIME 3600*24*7 
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8.2.13. CSTOLOWER 


[ C$TOLOWER Built-In Subroutine Syntax 


CALL "C$TOLOWER" USING data-item, BY VALUE convert-length 


This routine will converts the convert-length (a numeric literal or data item) leading char- 
acters of data-item (an alphanumeric identifier) to lower-case. 


The convert-length argument must be specified BY VALUE (see [CALL], page 293). Any 
characters in data-item after the convert-length point will remain unchanged. 


If convert-length is negative or zero, no conversion will be performed. 
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8.2.14. CSTOUPPER 


[ C$TOUPPER Built-In Subroutine Syntax 


CALL "C$TOUPPER" USING data-item, BY VALUE convert-length 


This routine will converts the convert-length (a numeric literal or data item) leading char- 
acters of data-item (an alphanumeric identifier) to upper-case. 


The convert-length argument must be specified BY VALUE (see [CALL], page 293). Any 
characters in data-item after the convert-length point will remain unchanged. 


If convert-length is negative or zero, no conversion will be performed. 
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8.2.15. CBL_AND 


( CBL_AND Built-In Subroutine Syntax } 


CALL "CBL_AND" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs a bit-by-bit logical AND operation 
Arg 1 Arg 2 Arg 2 between the left-most 8*byte-length corresponding bits of 
Bit Bit Bit item-1 and item-2, storing the resulting bit string into item-2. 


SSss=  SSS55 S555 The truth table shown to the left documents the AND process. 


data item and item-2 must be a data item. The length of 


) 

0 The item-1 argument may be an alphanumeric literal or a 
6) 

1 both item-1 and item-2 must be at least 8* byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.16. CBL_CHANGE_DIR 


( CBL_CHANGE_DIR Built-In Subroutine Syntax 


CALL "CBL_CHANGE_DIR" USING directory-path 


This routine makes directory-path (an alphanumeric literal or identifier) the current direc- 
tory. 

The return code of the operation, which will be either 0=Success or 128=failure, is 
returned in the RETURN-CODE special register (see [Special Registers], page 265). 

The directory change remains in effect until the program terminates (in which the original 
current directory at the time the program was started will be automatically restored) or 
until another CBL_CHANGE_DIR or a C$CHDIR built-in system subroutine (see [CSCHDIR], 
page 541) is executed. 
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8.2.17. CBL_-CHECK_FILE_EXIST 


[ 


CBL_CHECK_FILE_EXIST Built-In Subroutine Syntax 


CALL "CBL_CHECK_FILE_EXIST" USING file-path, file-info 


With this routine you may retrieve the size of the file specified as the file-path argument (an 
alphanumeric literal or identifier) and the date/time that file was last modified. File size 
information may not be available in the particular GnuCOBOL build / Operating System 
combination you are using and may therefore always be returned as zero. 


The information is returned to the file-info argument, which is defined as the following 


16-byte area: 


O01 file-info. 


05 
05 
05 
05 
05 
05 
05 
05 


File-Size-In-Bytes 
Mod-DD 

Mod-MO 

Mod-YYYY 

Mod-HH 

Mod-MM 

Mod-SS 

FILLER 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


9(18) 
9(2) 
9(2) 
9(4) 
9(2) 
9(2) 
9(2) 
9(2) 


CO} 


i 


COMP. 


CO} 


<= 


COMP. 


CO} 
CO} 
CO} 


zz 


COMP. 


2 
‘U0 'v0 'vU VU Uv 'U 'U 


*> Modification Date 


*> Modification Time 


*> Always 00 


If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE special 
register (see [Special Registers], page 265). Failure to retrieve the needed statistics on the 


file will cause a 


RETURN-CODE special register value of 35 to be passed back. Supplying 


less than two arguments will generate a 128 RETURN-CODE special register value. 
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8.2.18. CBL_CLOSE_FILE 


( CBL_CLOSE_FILE Built-In Subroutine Syntax 


CALL "CBL_CLOSE_FILE" USING file-handle 


The CBL_CLOSE_FILE subroutine closes a byte stream file previously opened by either the 
CBL_OPEN_FILE built-in system subroutine (see [CBL_OPEN_FILE], page 586) or CBL_ 
CREATE_FILE built-in system subroutine (see [CBL_CREATE_FILE], page 560) subroutines. 


If the file defined by the file-handle argument (a PIC X(4) USAGE COMP-X data item) 
was opened for output, an implicit CBL_FLUSH_FILE built-in system subroutine (see 
[(CBL_FLUSH_FILE], page 568) will be performed before the file is closed. 

If the subroutine is successful, a value of 0 will be returned in the RETURN-CODE special 
register (see [Special Registers], page 265). Failure will cause a RETURN-CODE special 
register value of -1 to be passed back. 
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8.2.19. CBL_COPY_FILE 


( CBL_COPY_FILE Built-In Subroutine Syntax } 


CALL "CBL_COPY_FILE" USING src-file-path, dest-file-path 


Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the cp 
(Unix/OSX) or COPY (Windows) command. 


Both arguments may be alphanumeric literals or identifiers. 


If the attempt to copy the file fails (for example, it or the destination directory doesn’t 
exist), the RETURN-CODE special register (see [Special Registers], page 265) will be set to 
128; on successful completion it will be set to 0. 
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8.2.20. CBL_CREATE_DIR 


( CBL_CREATE_DIR Built-In Subroutine Syntax } 


CALL "CBL_CREATE_DIR" USING dir-path 


With this routine you may create a new directory — the name of which is supplied as the 
dir-path argument (an alphanumeric literal or identifier). 


Only the lowest-level directory (last) in the specified path can be created — all others 
must already exist. This subroutine will not behave as a mkdir -p (Unix) or mkdir /p 
(Windows). 

The RETURN-CODE special register (see [Special Registers], page 265) will be set to the 
return code of the operation; the value will be either 0=Success or 128=failure. 
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8.2.21. CBL_CREATE_FILE 


( CBL_CREATE_FILE Built-In Subroutine Syntax 


CALL "CBL_CREATE_FILE" USING file-path, 2, 0, 0, file-handle 


The CBL_CREATE_FILE subroutine creates the new file specified using the file-path argument 
and opens it for output as a byte-stream file usable by CBL_WRITE_FILE built-in system 
subroutine (see [CBL-WRITE-_FILE], page 593). 

Arguments 2, 3 and 4 should be coded as the constant values shown. CBL_CREATE_FILE 
is actually a special-case of the CBL_OPEN_FILE built-in system subroutine (see 
[CBL_OPEN-_FILE], page 586) routine — see that routine for a description of the meanings 
of arguments 2, 3 and 4. 

A file-handle (PIC X(4) USAGE COMP-X) will be returned, for use on any subsequent 
CBL_WRITE_FILE built-in system subroutine (see [CBL_WRITE_FILE], page 593) or CBL_ 
CLOSE_FILE built-in system subroutine (see [CBL._CLOSE_FILE], page 557) calls. 

The success or failure of the subroutine will be reported back in the RETURN-CODE 
special register (see [Special Registers], page 265), with a value of -1 indicating an invalid 
argument and a value of 0 indicating success. 
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8.2.22. CBL_DELETE_DIR 


( CBL_DELETE_DIR Built-In Subroutine Syntax } 


CALL "CBL_DELETE_DIR" USING dir-path 


This subroutine deletes an empty directory. 

The only argument — dir-path (an alphanumeric literal or identifier) — is the name of 
the directory to be deleted. 

Only the lowest-level directory (last) in the specified path will be deleted, and that 
directory must be empty to be deleted. 


The RETURN-CODE special register (see [Special Registers], page 265) will be set to the 
return code of the operation; the value will be either 0=Success or 128=failure. 
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8.2.23. CBL_DELETE_FILE 


( CBL_DELETE_FILE Built-In Subroutine Syntax 


CALL "CBL_DELETE_FILE" USING file-path 


This routine deletes the file specified by the file-path argument (an alphanumeric literal or 
identifier) just as if that were done using the rm (Unix/OSX) or ERASE (Windows) command. 


If the attempt to delete the file fails (for example, it doesn’t exist), the _RETURN-CODE 
special register (see [Special Registers], page 265) will be set to 128; on successful completion 
it will be set to 0. 
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8.2.24. CBL_EQ 


CBL_EQ Built-In Subroutine Syntax ] 


CALL "CBL_EQ" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs a bit-by-bit comparison between 
Arg 1 Arg 2 Arg 2 the left-most 8*byte-length corresponding bits of item-1 and 
Bit Bit Bit item-2, storing the resulting bit string into item-2. The truth 


Sess SS555 S555 table shown to the left documents the EQ process. 


The item-1 argument may be an alphanumeric literal or a 
data item and item-2 must be a data item. The length of 
both item-1 and item-2 must be at least 8*byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.25. CBL_ERROR_PROC 


( CBL_ERROR_PROC Built-In Subroutine Syntax } 


CALL "CBL_ERROR_PROC" USING function, program-pointer 


This routine registers a general error-handling routine. 


The function argument must be a numeric literal or a 32-bit binary data item (USAGE 
BINARY-LONG, for example) with a value of 0 or 1. A value of 0 means that you will be 
registering (“installing”) an error procedure while a value of 1 indicates you’re de-registering 
(“uninstalling”) a previously-installed error procedure. 


The program-pointer must be a data item with a USAGE (see [USAGE], page 232) of 
PROGRAM-POINTER containing the address of your error procedure. This item should be given 
a value using the SET Program-Pointer statement (see [SET Program-Pointer], page 383). 
If the error procedure is written in GnuCOBOL, it must be a subroutine, not a user-defined 
function. 


A success (0) or failure (non-0) result will be passed back in the RETURN-CODE special 
register (see [Special Registers], page 265). 

A custom error procedure will trigger when a runtime error condition is encountered. 
An error procedure may be registered by a main program or a subprogram, but regardless 
of from where it was registered, it applies to the overall program compilation group and 
will trigger when a runtime error occurs anywhere in the executable program. If the error 
procedure was defined by a subprogram, that program must be loaded at the time the error 
procedure is executed. 


An error procedure may be used to take whatever actions might be warranted to display 
additional information or to gracefully close down work in progress, but it cannot prevent 
the termination of program execution; should the error procedure not issue its own STOP 
RUN, control will return back to the standard error routine when the error procedure exits. 


The code within the handler will be executed and — once the handler issues a return, 
if it was written in C, or an EXIT PROGRAM statement (see [EXIT], page 328) or GOBACK 
statement, if it was written in GnuCOBOL, the system-standard error handling routine 
will be executed. 


Only one user-defined error procedure may be in effect at any time. 


The following is a sample GnuCOBOL program that registers an error procedure. The 
output of that program is shown as well. As as you can see, the error handler’s messages 
appear followed by the standard GnuCOBOL message. 


1. IDENTIFICATION DIVISION. 
PROGRAM-ID. DemoERRPROC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


aP WD 
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6 01 Err-Proc-Address USAGE PROGRAM-POINTER. 
ike PROCEDURE DIVISION. 

8. Si. 

9. DISPLAY ’Program is starting’ 

10. SET Err-Proc-Address TO ENTRY ’ErrProc’ 

11. CALL ’CBL_ERROR_PROC’ USING 0, Err-Proc-Address 
12. CALL ’?Tilt’ *> THIS DOESN’T EXIST!!!! 

13. DISPLAY ’Program is stopping’ 

14. STOP RUN 

15. : 

16. END PROGRAM DemoERRPROC. 

17. 

18. IDENTIFICATION DIVISION. 

19. PROGRAM-ID. ErrProc. 

20. PROCEDURE DIVISION. 

21%, 000-Main. 

22. DISPLAY ’Error: ’ FUNCTION EXCEPTION-LOCATION 
23. DISPLAY ” > FUNCTION EXCEPTION-STATEMENT 
24. DISPLAY ” > FUNCTION EXCEPTION-FILE 

25. DISPLAY ” > FUNCTION EXCEPTION-STATUS 

26. DISPLAY ’*** Returning to Standard Error Routine ***’ 
27. EXIT PROGRAM 

28. : 

29. END PROGRAM ErrProc. 


When executed, this sample program generates the following console output. 


E: \Programs\Demos>demoerrproc 
Program is starting 
Error: DemoERRPROC; Si; 12 
CALL 
00 
EC-PROGRAM-NOT-FOUND 
*** Returning to Standard Error Routine *** 
DEMOERRPROC.cb1l: 27: libcob: Cannot find module ’Tilt’ 


E: \Programs\Demos> 
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8.2.26. CBL_EXIT_PROC 


( CBL_EXIT_PROC Built-In Subroutine Syntax } 


CALL "CBL_EXIT_PROC" USING function, program-pointer 


This routine registers a general exit-handling routine. 


The function argument must be a numeric literal or a 32-bit binary data item (USAGE 
BINARY-LONG, for example) with a value of 0 or 1. A value of 0 means that you will be 
registering (“installing”) an exit procedure while a value of 1 indicates you’re deregistering 
(“uninstalling”) a previously-installed exit procedure. 


The program-pointer must be a data item with a USAGE (see [USAGE], page 232) of 
PROGRAM-POINTER containing the address of your exit procedure. 


A success (0) or failure (non-0) result will be passed back in the RETURN-CODE special 
register (see [Special Registers], page 265). 

An exit procedure, once registered, will trigger whenever a STOP RUN statement (see 
[STOP], page 399) or a GOBACK statement (see [GOBACK], page 334) is executed anywhere 
in the program. The exit procedure may execute whatever code is desired to undertake 
an orderly shut down of the program. Once the exit procedure terminates by executing an 
EXIT PROGRAM statement (see [EXIT], page 328) or a GOBACK statement, the system-standard 
program termination routine will be executed. 


Only one user-defined exit procedure may be in effect at any time. 


The following is a sample GnuCOBOL program that registers an exit procedure. The 
output of that program is shown as well. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. demoexitproc. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 Exit-Proc-Address USAGE PROGRAM-POINTER. 
PROCEDURE DIVISION. 
000-Register-Exit-—Proc. 
SET Exit-Proc-Address TO ENTRY "ExitProc" 
CALL "CBL_EXIT_PROC" USING 0, Exit-Proc-Address 
IF RETURN-CODE NOT = 0 
DISPLAY ’Error: Could not register Exit Procedure’ 
END-IF 


099-Now-Test-Exit-Proc. 
DISPLAY 
?Executing a STOP RUN...’ 
END-DISPLAY 
GOBACK. 
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END PROGRAM demoexitproc. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. ExitProc. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 Display-Date PIC XXXX/XX/XX. 
01 Display-Time PIC XX/XX/XX. 
01 Now PIC X(8). 

01 Today PIC X(8). 
PROCEDURE DIVISION. 

000-Main. 


DISPLAY ’*** STOP RUN has been executed ***’ 
ACCEPT Today FROM DATE YYYYMMDD 
ACCEPT Now FROM TIME 
MOVE Today TO Display-Date 
MOVE Now TO Display-Time 
INSPECT Display-Time REPLACING ALL ’/’ BY °:?’ 
DISPLAY 7 *** > Display-Date ’ ’ Display-Time ’ KK? 
GOBACK. 
END PROGRAM ExitProc. 
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8.2.27. CBL_FLUSH_FILE 


( CBL_FLUSH_FILE Built-In Subroutine Syntax 


CALL "CBL_FLUSH_FILE" USING file-handle 


In Micro Focus COBOL, calling this subroutine flushes any as-yet unwritten buffers for the 
(output) file whose file-handle is specified as the argument to disk. 


This routine is non-functional in GnuCOBOL. It exists only to provide compatibility for 
applications that may have been developed for Micro Focus COBOL. 
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8.2.28. CBL_GC_FORK 


[ CBL_GC_FORK Built-In Subroute Syntax ] 


CALL "CBL_GC_FORK" USING Child-PID 


CBL_GC_FORK allows you to fork the current COBOL process to a new one. 


The current content of the process’s storage (including LOCAL-STORAGE) will be 
identical, any file handles get invalid in the new process, positions and file and record locks 
are only available to the original process. 


This system routine is not available on Windows (exception: GCC on Cygwin). 
Parameters: none 


Returns: pid (the child process gets ’0’ returned, the calling process gets the pid of the 
created child). 


Negative values are returned for system dependant error codes and -1 if the function is 
not available on the current system. 


CBL_GC_FORK allows you to fork the current COBOL process to a new one. The current 
content of the process’ storage (including LOCAL-STORAGE) will be identical, any file handles 
get invalid in the new process, positions and file / record locks are only available to the 
original process. This system routine is not available on Windows (exception: gcc on 
Cygwin). Parameters: none Returns: pid (the child process gets 0 returned, the calling 
process gets the pid of the created children). Negative values are returned for system 
dependant error codes and -1 if the function is not available on the current system. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. prog. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
O01 CHILD-PID PIC S9(9) BINARY. 
01 WAIT-STS PIC S9(9) BINARY. 
PROCEDURE DIVISION. 
CALL "CBL_GC_FORK" RETURNING CHILD-PID END-CALL 
EVALUATE TRUE 
WHEN CHILD-PID = ZERO 
PERFORM CHILD-CODE 
WHEN CHILD-PID > ZERO 
PERFORM PARENT-CODE 
WHEN CHILD-PID = -1 
DISPLAY ’CBL_GC_FORK is not available on the current’ 
> system!’ 
PERFORM CHILD-CODE 
MOVE O TO CHILD-PID 
PERFORM PARENT-CODE 
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WHEN OTHER 
MULTIPLY -1 BY CHILD-PID END-MULTIPLY 
DISPLAY ’CBL_GC_FORK returned system error: ’ CHILD-PID 
END-EVALUATE 


STOP RUN. 

CHILD-CODE. 
CALL "C$SLEEP" USING 1 END-CALL 
DISPLAY "Hello, I am the child" 
MOVE 2 TO RETURN-CODE. 


PARENT-CODE. 
DISPLAY "Hello, I am the parent" 
CALL "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS 
MOVE 0 TO RETURN-CODE 
EVALUATE TRUE 
WHEN WAIT-STS >= 0 
DISPLAY ’Child ended with status: ’ WAIT-STS 
WHEN WAIT-STS = -1 
DISPLAY ’CBL_GC_WAITPID is not available on the ’ 
>current system!’ 
WHEN WAIT-STS < -1 
MULTIPLY -1 BY WAIT-STS END-MULTIPLY 
DISPLAY ’CBL_GC_WAITPID returned system error: ’ WAIT-STS 
END-EVALUATE. 


Chapter 8 - Functions 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 571 


8.2.29. CBL_GC_GETOPT 


[ CBL_GC_GETOPT Built-In Subroutine Syntax 


CALL "CBL_GC_GETOPT" USING BY REFERENCE SHORTOPTIONS LONGOPTIONS LONGIND 
BY VALUE LONG-ONLY 
BY REFERENCE RETURN-CHAR OPT-VAL 


CBL_GC_GETOPT adapts the well-known option parser, getopt, to GnuCOBOL. 
The usage of this system routine is described by the following example. 


IDENTIFICATION DIVISION. 

PROGRAM-ID. PROG. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

78 SHORTOPTIONS VALUE "jkl". 

01 LONGOPTIONS. 

05 OPTIONRECORD OCCURS 2 TIMES. 

10 OPTIONNAME PIC X(25). 
10 HAS-VALUE PIC 9. 


10 VALPOINT POINTER VALUE NULL. 
10 RETURN-VALUE PIC X(4). 

01 LONGIND PIC 99. 

01 LONG-ONLY PIC 9 VALUE 1. 

01 RETURN-CHAR PIC X(4). 

01 OPT-VAL PIC X(10). 

01 COUNTER PIC 9 VALUE 0. 


We first need to define the necessary fields for getopt’s shortoptions, longoptions, 
longoption index (longind), long-only-option (long-only) and also the fields for return 
values return-char and opt-val (arbitrary size with trimming, see return codes). 

The shortoptions are written down as an alphanumeric field (i.e., a string with arbitrary 
size) as follows: 

"ab:c::d" 

This means we want getopt to look for short options named ‘a’, ‘b’, ‘c’ or ‘d’, require 
an option value for ‘b’, and accept an optional one for ‘c’. 

The longoptions are defined as a table of records with oname, has-value, valpoint 
and val.! 

oname defines the name of a longoption. has-value defines if an option value is de- 
manded (has-val = 1), optional (has-val = 2) or not required (has-val = 0). 

valpoint is a pointer used to specify an address to save getopt’s return value to. The 
pointer is optional. If it is NULL, getopt returns a value as usual. If you use the pointer it 


2 Say what? the discussion and code seem to have diverged. 
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has to point to a PIC X(4) field. The field val is a PIC X(4) character which is returned if 
the longoption was recognized. 


The longoption structure is immutable! You can only vary the number of records. 
Now we have the tools to run CBL_GC_GETOPT within the procedure division. 
PROCEDURE DIVISION. 


MOVE "version" to OPTIONNAME (1). 
MOVE O TO HAS-VALUE (1). 

MOVE ‘V’? TO RETURN-VALUE (1). 
MOVE "verbose" TO OPTIONNAME (2). 
MOVE O TO HAS-VALUE (2). 

MOVE ‘Vv’? TO RETURN-VALUE (2). 


PERFORM WITH TEST AFTER UNTIL RETURN-CODE = -1 
CALL ’?CBL_GC_GETOPT’ USING 
BY REFERENCE SHORTOPTIONS LONGOPTIONS LONGIND 
BY VALUE LONG-ONLY 
BY REFERENCE RETURN-CHAR OPT-VAL 
END-CALL 
DISPLAY RETURN-CHAR END-DISPLAY 
DISPLAY OPT-VAL END-DISPLAY 
END-PERFORM 
STOP RUN. 


The example shows how we initialize all parameters and call the routine until CBL_GC_ 
GETOPT runs out of options and returns -1. 


return-char might contain the following regular character if an option was recognized: 


? undefined or ambiguous option 

ab non-option (only if first byte of so is ‘-’) 

0) valpoint != NULL and we are writing the return value to the specified address 
= no more options (or reach the first non-option if first byte of shortoptions is 


+?) 


The return-codes of CBL_GC_GETOPT are: 


1 a non-option (only if first byte of so is ‘-’) 

0 valpoint != NULL and we are writing the return value to the specified address 

-1 no more options (or reach the first non-option if first byte of shortoptions is 
“4? 

2 truncated option value in opt-val (because opt-val was too small) 

3 a regular answer from getopt 
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8.2.30. CBL_GC_HOSTED 


[ CBL_GC_HOSTED Built-In Subroutine Syntax 


CALL "CBL_GC_HOSTED" USING ARG-1 ARG-2 


Note replaces CBL_OC_HOSTED which is kept as a legacy item. 


CBL_GC_HOSTED provides access to the following C hosted variables: 
argc binary-long by value 
argv pointer to char ** 


stdin, stdout, stderr 
pointer 


errno giving address of errno in pointer to binary-long, use based for more 
Direct access and conditional access to the following variables: 

tzname pointer to pointer to array of two char pointers 

timezone C long, will be seconds west of UTC 

daylight C int, will be 1 during daylight savings 


The system will need HAVE TIMEZONE defined for these to return anything meaningful. 
Attempts made when they are not available will return 1 from CBL GC HOSTED. 


It returns 0 when match, 1 on failure, case matters as does length, "arg" won’t match. 
The usage of this system routine is described by the following example. 
IDENTIFICATION DIVISION. 
PROGRAM-ID. HOSTED. 


DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 Arge BINARY-LONG. 
01 Argv POINTER. 
O1 Stdin POINTER. 
O1 Stdout POINTER. 
O1 Stderr POINTER. 
O01 Errno POINTER. 
O1 Err BINARY-LONG BASED. 
O1 Domain FLOAT-LONG VALUE 3.0. 
O01 Tzname POINTER. 
O1 Tznames POINTER BASED. 
05 Tzs POINTER OCCURS 2. 


01 Timezone BINARY-LONG. 
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01 Daylight BINARY-SHORT. 


*> 
PROCEDURE DIVISION. 
call "CBL_GC_HOSTED" using stdin "stdin" 
display "stdin : " stdin 
call "feof" using by value stdin 
display "feof stdin : " return-code 
call "CBL_GC_HOSTED" using stdout "stdout" 
display "stdout : " stdout 
call "fprintf" using by value stdout by content "Hello" & x"0a" 
call "CBL_GC_HOSTED" using stderr "stderr" 
display "stderr : " stderr 
call "fprintf" using by value stderr by content "on err" & x"0a" 
call "CBL_GC_HOSTED" using arge "argc" 
display "argc : " argc 
call "CBL_GC_HOSTED" using argv "argv" 
display "argv : " argv 
call "args" using by value argc argv 
call "CBL_GC_HOSTED" using errno "errno" 
display "errno : " errno 
set address of err to errno 
display "errno : " err 
call "acos" using by value domain 
display "errno after acos(3.0): " err ", EDOM is 33" 
call "CBL_GC_HOSTED" using arge "arg" 
display "’arg’ lookup : " return-code 
call "CBL_GC_HOSTED" using null "argc" 
display "null with argc : " return-code 
display "argc is still : " argc 
*> the following only returns zero if the system has HAVE_TIMEZONE set 
call "CBL_GC_HOSTED" using daylight "daylight " 
display '"’timezone’ lookup : " return-code 
if return-code not = 0 
display "system doesn’t has timezone" 
else 
display "timezone is : " timezone 
call "CBL_GC_HOSTED" using daylight "daylight " 
display "’daylight’ lookup : " return-code 
display "daylight is : " daylight 


set environment "TZ" to "PST8PDT" 
call static "tzset" returning omitted on exception 
continue end-call 
call "CBL_GC_HOSTED" using tzname "tzname" 
display "’tzname’ lookup : " return-code 
*> tzs(1) will point to z"PST" and tzs(2) to z"PDT" 
if return-code equal 0 and tzname not equal null then 
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set address of tznames to tzname 
if tzs(1) not equal null then 


display "tzs #1 : " tzs(1) 
end-if 
if tzs(2) not equal null then 
display "tzs #2 : " tzs(2) 
end-if 
end-if 
end-if 
goback. 


end program hosted. 


Note that the legacy name of this routine that starts with CBL_OC is deprecated, as is 
NANOSLEEP but will still work. It is recommended that all library routines names starting 
with CBL_OC are replaced with CBL_GC to minimise issues. 
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8.2.31. CBL_GC_NANOSLEEP 


[ CBL_GC_NANOSLEEP Built-In Subroutine Syntax 


CALL "CBL_GC_NANOSLEEP" USING nanoseconds-to-sleep 


Note replaces CBL_OC_NANOSLEEP which is kept as a legacy item. 


This subroutine puts the program to sleep for the specified number of nanoseconds. 

The effective granularity of nanoseconds-to-sleep values will depend upon the granularity 
of the system clock your computer is using and the timing granularity of the operating 
system that computer is running. 

For example, you will not expect to see any difference between values of 1, 100, 500 or 
1000, but you should see a difference between values such as 250000000 and 500000000. 

The nanoseconds-to-sleep argument is a numeric literal or data item. 

There are one billion nanoseconds in a second, so if you wanted to put the program to 
sleep for 1/4 second you’d use a nanoseconds-to-sleep value of 250000000. 

Note that the legacy name of this routine starts with “CBL_OC” is deprecated, as is 
HOSTED, but will still work. It is recommended that all library routines names starting with 
“CBL_OC” are replaced with “CBL_GC” to minimise issues. 
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8.2.32. CBL_GC_PRINTABLE 


[ CBL_GC_PRINTABLE Built-In Subroutine Syntax j 


CALL "CBL_GC_PRINTABLE" USING data-item [ , char ] 


Note replaces C$PRINTABLE which is kept as a legacy item. 


The CBL_GC_PRINTABLE subroutine converts the contents of the data-item specified as the 
first argument to printable characters. 


Those characters that are deemed printable (as defined by the character set used by 
data-item) will remain unchanged, while those that are not printable will be converted to 
the character specified as the second argument. 


If no char argument is provided, a period (‘.’) will be used. 
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8.2.33. CBL_GC_WAITPID 


[ CBL_GC_WAITPID Built-In Subroutine Syntax 


CALL "CBL_GC_WAITPID" USING ARG-1 


CBL_GC_WAITPID allows you to wait until another system process ended. 


Additionally you can check the process’s return code. 
Parameters: none 


Returns: function-status / child-status 


Negative values are returned for system dependant error codes and -1 if the function is 


not available on the current system. 


CALL "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS 


MOVE 0 TO RETURN-CODE 
DISPLAY ’CBL_GC_WAITPID ended with status: ’ WAIT-STS 
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8.2.34. CBL_GET_CSR_POS 


( CBL_GET_CSR_POS Built-In Subroutine Syntax } 


CALL "CBL_GET_CSR_POS" USING cursor-locn-buffer 


This subroutine will retrieve the current cursor location on the screen, returning a 2-byte 
value into the supplied cursor-locn-buffer. The first byte of cursor-locn-buffer will receive 
the current line (row) location while the second receives the current column location. 

The returned location data will be in binary form, and will be based upon starting values 
of 0, meaning that if the cursor is located at line 15, column 12 at the time this routine is 
called, a value of (14,11) will be returned. 

The following is a typical cursor-locn-buffer definition: 

01 CURSOR-LOCN-BUFFER. 
05 CURSOR-LINE USAGE BINARY-CHAR. 
05 CURSOR-COLUMN USAGE BINARY-CHAR. 

Values of 1 (Line) and 1 (column) will be returned if GnuCOBOL was not generated to 

include screen I/O. 
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8.2.35. CBL_GET_CURRENT_DIR 


( CBL_GET_CURRENT_DIR Built-In Subroutine Syntax 


CALL "CBL_GET_CURRENT_DIR" USING BY VALUE 0, 


This retrieves the fully-qualified pathname of the current directory, saving up to length 
characters of that name into buffer. 

The first argument is unused, but must be specified. It must be specified BY VALUE (see 
[CALL], page 293). 

The length argument must be specified BY VALUE. The buffer argument must be specified 
BY REFERENCE. 

The value specified for the length argument (a numeric literal or data item) should not 
exceed the actual length of buffer argument. 

If the value specified for the length argument is LESS THAN the actual length of buffer 
argument, the current directory path will be left-justified and space filled within the first 
length bytes of buffer — any bytes in buffer after that point will be unchanged. 

If the routine is successful, a value of 0 will be returned to the RETURN-CODE special 
register (see [Special Registers], page 265). If the routine failed because of a problem with 
an argument (such as a negative or 0 length), a value of 128 will result. Finally, if the 1% 
argument value is anything but zero, the routine will fail with a 129 value. 
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8.2.36. CBL_GET_SCR_SIZE 


( CBL_GET_SCR_SIZE Built-In Subroutine Syntax } 


CALL "CBL_GET_SCR_SIZE" USING no-of-lines, no-of-cols 


Use this subroutine to retrieve the current console screen size. 


When the system is running in a windowed environment, this will be the sizing of the 
console window in which the program is executing. When the system is not running a 
windowing environment, the physical console screen attributes will be returned. In envi- 
ronments such as a Windows console window, where the logical size of the window may 
far exceed that of the physical console window, the size returned will be that of the phys- 
ical console window. Two one-byte values will be returned — the first will be the current 
number of lines (rows) while the second will be the number of columns. 


The returned size data will be in binary form. 

The following are typical no-of-lines and no-of-columns definitions: 
01 NO-OF-LINES USAGE BINARY-CHAR. 
01 NO-OF-COLUMNS USAGE BINARY-CHAR. 


GnuCOBOL run-time screen management must have been initialized prior to CALLing 
this routine in order to receive meaningful values. This means that a DISPLAY data-item 
statement (see [DISPLAY data-item], page 311) or a ACCEPT data-item statement (see 
[ACCEPT data-item], page 272) must have been executed prior to executing the CALL 
statement. 


Zero values will be returned if the screen has not been initialized and values of 24 (lines) 
and 80 (columns) will be returned if GnuCOBOL was not generated to include screen I/O. 
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8.2.37. CBL_IMP 


( CBL_IMP Built-In Subroutine Syntax } 


CALL "CBL_IMP" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs a bit-by-bit logical implies pro- 
Arg 1 Arg 2 Arg 2 cess between the left-most 8* byte-length corresponding bits of 
Bit Bit Bit item-1 and item-2, storing the resulting bit string into item-2. 


SSss=  SSS55 0 S555 The truth table shown to the left documents the IMP process. 


1 

1 The item-1 argument may be an alphanumeric literal or a 
0 data item and item-2 must be a data item. The length of 
1 both item-1 and item-2 must be at least 8* byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.38. CBL_NIMP 


( CBL_NIMP Built-In Subroutine Syntax } 


CALL "CBL_NIMP" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs the negation of a bit-by-bit logi- 
Arg 1 Arg 2 Arg 2 cal implies process between the left-most 8*byte-length cor- 
Bit Bit Bit responding bits of item-1 and item-2, storing the resulting bit 


SSSS5 0 SS555 °° S555 string into item-2. The truth table shown to the left docu- 
ments the NIMP process. 


The item-1 argument may be an alphanumeric literal or a 
data item and item-2 must be a data item. The length of 
both item-1 and item-2 must be at least 8*byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.39. CBL_NOR 


[ 


CBL_NOR Built-In Subroutine Syntax } 


CALL "CBL_NOR" USING item-1, item-2, BY VALUE byte-length 


Old Old New 
Arg 1 Arg 2 Arg 2 
Bit Bit Bit 


This subroutine performs the negation of a bit-by-bit logical 
or’ process between the left-most 8*byte-length correspond- 
ing bits of item-1 and item-2, storing the resulting bit string 
into item-2. The truth table shown to the left documents the 
NOR process. 


The item-1 argument may be an alphanumeric literal or a 
data item and item-2 must be a data item. The length of 
both item-1 and item-2 must be at least 8*byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 


Registers], page 265). 
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8.2.40. CBL_NOT 


( CBL_NOT Built-In Subroutine Syntax } 


CALL "CBL_NOT" USING item-1, BY VALUE byte-length 


This subroutine “flips” the left-most 8*byte-length bits of item-1, changing 0 bits to 1, and 
1 bits to 0. The changes are made directly im item-1. 

The item-1 argument must be a data item. The length of item-1 must be at least 
8* byte-length. 

The byte-length argument may be a numeric literal or data item, and must be passed 
using BY VALUE (see [CALL], page 293). 

Any bits in item-1 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.42. CBL_OPEN_FILE 


( CBL_OPEN_FILE Built-In Subroutine Syntax 


CALL "CBL_OPEN_FILE" USING file-path, access-mode, 0, 0, handle 


This routine opens an existing file for use as a byte-stream file usable by CBL_.WRITE_FILE 
or CBL_READ_FILE. 


The file-path argument is an alphanumeric literal or data-item. 


The access-mode argument is a numeric literal or data item with a PIC X USAGE COMP-X 
(or USAGE BINARY-CHAR) definition; it specifies how you wish to use the file, as follows: 


1 input (read-only) 
2 output (write-only) 
3 input and/or output 


The third and fourth arguments would specify a locking mode and device specification, 
respectively, but they’re not implemented in GnuCOBOL (currently, at least) — just specify 
each as 0. 

The final argument (handle) is a PIC X(4) USAGE COMP-X item that will receive the 
handle to the file. That handle is used on all other byte-stream functions to reference this 
specific file. 

A RETURN-CODE special register (see [Special Registers], page 265) value of -1 indicates 
an invalid argument, while a value of 0 indicates success. A value of 35 means the file does 
not exist. 


Chapter 8 - Functions 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 587 


8.2.43. CBL_OR 


( CBL_OR Built-In Subroutine Syntax 


CALL "CBL_OR" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs a bit-by-bit logical or process be- 
Arg 1 Arg 2 Arg 2 tween the left-most 8*byte-length corresponding bits of item- 
Bit Bit Bit 1 and item-2, storing the resulting bit string into item-2. The 


SSss=  SSS55 S555 truth table shown to the left documents the OR process. 


data item and item-2 must be a data item. The length of 


) 

1 The item-1 argument may be an alphanumeric literal or a 
1 

1 both item-1 and item-2 must be at least 8* byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.44. CBL_READ_FILE 


( CBL_READ_FILE Built-In Subroutine Syntax 


CALL "CBL_READ_FILE" USING handle, offset, nbytes, flag, buffer 


This routine reads nbytes of data starting at byte number offset from the byte-stream file 
defined by handle into buffer. 


The handle argument (PIC X(4) USAGE COMP-X) must have been populated by a prior 
call to CBL_OPEN_FILE built-in system subroutine (see [CBL_OPEN_FILE], page 586). 


The offset argument (PIC X(8) USAGE COMP-X) defines the location in the file of the first 
byte to be read. The first byte of a file is byte offset 0 and MUST be preset to zero for first 
use. 


The nbytes argument (PIC X(4) USAGE COMP-X) specifies how many bytes (maximum) 
will be read. If the flag argument is specified as 128, the size of the file (in bytes) will 
be returned into the file offset argument (argument 2) upon completion. Not all operating 
system/GnuCOBOL environments may be able to retrieve file sizes in such cases, a value 
of zero will be returned. The only other valid value for flags is 0. This argument may be 
specified either as a numeric literal or as a PIC X USAGE COMP-X data item. 


Upon completion, the RETURN-CODE special register (see [Special Registers], page 265) 
will be set to 0 if the read was successful or to 10 if an "end-of-file" condition occurred. If 
a value of -1 is returned, a problem was identified with the subroutine arguments. 
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8.2.45. CBL_READ_KBD_CHAR 


[ CBL_READ_KBD_CHAR Build-In Subroutine Syntax } 


CALL "CBL_READ_KBD_CHAR" USING char RETURNING status-code. 


Waits until a character is typed from the terminal and then read it with no echo. 
Parameters: char PIC X. Receives the character that was typed, in ASCII. 
status-code PIC XX COMP-5. 


If RETURNING is not used the RETURN-CODE special register receives the status-code where 
zero is success and non-zero it is not. 


[Above information taken from MF WB manual]. 
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8.2.46. CBL_RENAME_FILE 


( CBL_RENAME_FILE Built-In Subroutine Syntax 


CALL "CBL_RENAME_FILE" USING old-file-path, new-file-path 


You may use this subroutine to rename a file. 


The file specified by old-file-path will be “renamed” to the name specified as new-file- 
path. Each argument may be an alphanumeric literal or data item. 


Despite what the name of this routine might make you believe, this routine is more than 
just a simple “rename” — it will actually move the file supplied as the 1** argument to the 
file specified as the 2nd argument. Think of it as a two-step sequence, first copying the 
old-file-path file to the new-file-path file and then a second step where the old-file-path is 
deleted. 


If the attempt to move the file fails (for example, it doesn’t exist), the RETURN-CODE 
special register (see [Special Registers], page 265) will be set to 128; on successful completion 
it will be set to 0. 
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8.2.47. CBL_SET_CSR_POS 


( CBL_SET_CSR_POS Build-In Subroutine Syntax } 


CALL "CBL_SET_CSR_POS" USING cursor-locn-buffer 


Set current cursor position on terminal. 

This subroutine will set the cursor location on the screen, using a 2-byte value into the 
supplied cursor-locn-buffer. The first byte of cursor-locn-buffer is for the line (row) location 
while the second sets the column location. 

The two byte data block must be in binary form, and will be based upon starting values 
of 0, meaning that if the routine is called with a value of (14,11) cursor will be located at 
line 15, column 12. 

The following is a typical cursor-locn-buffer definition: 

O01 CURSOR-LOCN-BUFFER. 
05 CURSOR-LINE USAGE BINARY-CHAR. 
05 CURSOR-COLUMN USAGE BINARY-CHAR. 


15 January 2023 Chapter 8 - Functions 


592 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


8.2.48. CBL-TOLOWER 


( CBL_TOLOWER Built-In Subroutine Syntax 


CALL "CBL_TOLOWER" USING data-item, BY VALUE convert-length 


This routine will convert the first convert-length (a numeric literal or data item) characters 
of data-item (an alpha-numeric identifier) to lower-case. 


The convert-length argument must be specified BY VALUE (see [CALL], page 293). It 
specifies how many (leading) characters in data-item will be converted — any characters 
after that will remain unchanged. 


If convert-length is negative or zero, no conversion will be performed. 


8.2.49. CBL_-TOUPPER 


f CBL_TOUPPER Built-In Subroutine Syntax 


CALL "CBL_TOUPPER" USING data-item, BY VALUE convert-length 


This routine will convert the first convert-length (a numeric literal or data item) characters 
of data-item (an alpha-numeric identifier) to upper-case. 


The convert-length argument must be specified BY VALUE (see [CALL], page 293). It 
specifies how many (leading) characters in data-item will be converted — any characters 
after that will remain unchanged. 


If convert-length is negative or zero, no conversion will be performed. 
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8.2.50. CBL_WRITE_FILE 


( CBL_WRITE_FILE Built-In Subroutine Syntax } 


CALL "CBL_WRITE_FILE" USING handle, offset, nbytes, 0, buffer 


This routine writes nbytes of data from buffer to the byte-stream file defined by handle 
starting at byte number offset within the file. 

The handle argument (PIC X(4) USAGE COMP-X) must have been populated by a prior call 
to CBL_OPEN_FILE. The offset argument (PIC X(4) USAGE COMP-X) defines the location 
in the file of the first byte to be written to. The first byte of a file is byte offset 0. 

The nbytes argument (PIC X(4) USAGE COMP-X) specifies how many bytes (maximum) 
will be written. 

Currently, the only allowable value for the flags argument is 0. This argument may be 
specified either as a numeric literal or as a PIC X(1) USAGE COMP-X data item. 

Upon completion, the RETURN-CODE special register (see [Special Registers], page 265) 
will be set to 0 if the write was successful or to 30 if an I/O error condition occurred. If a 
value of -1 is returned, a problem was identified with the subroutine arguments. 
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8.2.51. CBL_XOR 


( CBL_XOR Built-In Subroutine Syntax 


CALL "CBL_XOR" USING item-1, item-2, BY VALUE byte-length 


Old Old New This subroutine performs a bit-by-bit logical exclusive or pro- 
Arg 1 Arg 2 Arg 2 cess between the left-most 8* byte-length corresponding bits of 
Bit Bit Bit item-1 and item-2, storing the resulting bit string into item-2. 


SSss=  SSS55 S555 The truth table shown to the left documents the XOR process. 


6) ) 

1 1 The item-1 argument may be an alphanumeric literal or a 
0 1 data item and item-2 must be a data item. The length of 
1 0 both item-1 and item-2 must be at least 8* byte-length. 


The byte-length argument may be a numeric literal or data item, and must be specified 
using BY VALUE (see [CALL], page 293). 


Any bits in item-2 after the 8*byte-length point will be unaffected. 


A result of zero will be passed back in the RETURN-CODE special register (see [Special 
Registers], page 265). 
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8.2.52. SYSTEM 


( SYSTEM Built-In Subroutine Syntax } 


CALL "SYSTEM" USING command 


This subroutine submits command (an alphanumeric literal or data item) to a command 
shell for execution as if it were typed into a console/terminal window. 


A shell will be opened subordinate to the GnuCOBOL program issuing the call to SYSTEM. 


Output from the command (if any) will appear in the command window in which the 
GnuCOBOL program was executed. 

On a Unix system, the shell environment will be established using the default shell 
program. This is also true when using a GnuCOBOL build created with and for OSX or 
the Cygwin Unix emulator. 

With native Windows Windows/MinGW builds, the shell environment will be the Win- 
dows console window command processor (usually cmd.exe) appropriate for the version of 
Windows you're using. 

To trap output from the executed command and process it within the GnuCOBOL 
program, use a redirection (‘>’) to send the command output to a temporary file which you 
read from within the program once control returns. 

The exit status of the executed command will be available in the RETURN-CODE special- 
register. 
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8.2.53. X"91" 


( X"91" Built-In Subroutine Syntax } 


CALL X"91" USING return-code, function-code, binary-variable-arg 


The original Micro Focus version of this routine is capable of providing a wide variety of 
functions. GnuCOBOL supports just three of them: 


e Turning runtime switches (SWITCH-1, ... , SWITCH-8) on. 
e Turning runtime switches (SWITCH-1, ... , SWITCH-8) off. 
e Retrieving the number of arguments passed to a subroutine. 
The return-code argument must be a one-byte binary numeric data item (USAGE 


BINARY-CHAR is recommended). It will receive a value of 0 if the operation was successful, 
1 otherwise. 


The function-code argument must be either a numeric literal or a one-byte binary nu- 
meric data item (USAGE BINARY-CHAR is recommended). 

The third argument — variable-arg — is defined differently depending upon the function- 
code value, as follows: 


11 Sets and/or clears all eight of the COBOL switches (SWITCH-1 through 
SWITCH-8). See [SPECIAL-NAMES], page 92, for an explanation of those 
switches. 


The variable-arg argument should be an OCCURS 8 TIMES table of USAGE 
BINARY-CHAR. 


Each occurrence that is set to a value of zero prior to the CALL X"91" will cause 
the corresponding switch to be cleared. Each occurrence set to 1 prior to the 
CALL X"91" will cause the corresponding switch to be set. 


Values other than 0 or 1 will be ignored. 


12 Reads all eight of the COBOL switches (SWITCH-1 through SWITCH-8) 


The variable-arg argument should be an OCCURS 8 TIMES table of USAGE 
BINARY-CHAR. 


Each of the 1* eight occurrences of the array will be set to either 0 or 1 — 1 if 
the corresponding switch is set, 0 otherwise. 


16 Retrieves the number of arguments passed to the program executing the CALL 
X"91", saving that number into the variable-arg argument. That should be a 
binary numeric data item (USAGE BINARY-CHAR is recommended). 
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8.2.54. X" EA" 


[ X"E4" Built-In Subroutine Syntax } 


CALL X"E4" 


Use X"E4" to clear the screen. There are no arguments and no returned value. 


8.2.55. X"E5" 


[ X"E5" Built-In Subroutine Syntax 


CALL X"E5" 


The X"E5" routine will sound the PC “bell”. There are no arguments and no returned 
value. 
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8.2.56. X"F4" 


( X"F4" Built-In Subroutine Syntax 


CALL X"F4" USING byte, table 


This routine packs the low-order (rightmost) bit from each of the eight 1-byte items in table 
into the corresponding bit positions of the single-byte data item byte. 


The byte data item need be only a single byte in size. If it is longer, the excess will be 
unaffected by this subroutine. 


The table data item must be at least 8 bytes long. If it is longer, the excess will be 
ignored by this subroutine. 


Typically, table is defined similarly to the following: 


01 Table-Arg. 
05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR. 
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8.2.57. X"F5" 


( X"F5" Built-In Subroutine Syntax 


CALL X"F5" USING byte, table 


This routine unpacks each bit of the single-byte data item byte into the low-order (right- 
most) bit of each of the corresponding eight 1-byte items in table. The other seven bit 
positions of each of the first eight entries in table will be set to zero. 

The byte data item need be only a single byte in size. If it is longer, the excess will be 
unaffected by this subroutine. 

The table data item must be at least 8 bytes long. If it is longer, the excess will be 
ignored by this subroutine. 

Typically, table is defined similarly to the following: 

01 Table-Arg. 
05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR. 


End of Chapter 8 — Functions 
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9. Report Writer Usage 


9.1. RWCS Lexicon 


There are a number of terms that describe various aspects of the operation of the Report 
Writer Control System (RWCS). Understanding the meanings of these terms is vital to 
developing an understanding of the subject. 


Control Break 
An event that is triggered when a control field on an RWCS-generated report 
changes value. It is these events that trigger the generation of control heading 
and control footing groups. 


Control Field 

A field of data being presented within a detail group; as the various detail 
groups that comprise the report are presented, they are presumed to appear 
in sorted sequence of the control fields contained within them. As an example, 
a department-by-department sales report for a chain of stores would probably 
be sorted by store number and — within like store numbers — be further sorted 
by department number. The store number will undoubtedly serve as a control 
field for the report, allowing control heading groups to be presented before each 
sequence of detail groups for the same store and control footing groups to be 
presented after each such sequence. 


Control Footing 

A report group that appears immediately after one or more detail groups of 
an RWCS-generated report. Such are produced automatically as a result of a 
control break. This type of group typically serves as a summary of the detail 
group(s) that precede it, as might be the case on a sales report for a chain 
of stores, where the detail groups documenting sales for each department (one 
department per detail group) from the same store might be followed by a control 
footing that provides a summation of the department-by-department sales for 
that store. 


Control Heading 

A report group that appears immediately before one or more detail groups 
of an RWCS-generated report. Such are produced automatically as a result 
of a control break. This type of group typically serves as an introduction to 
the detail group(s) that follow, as might be the case on a sales report for a 
chain of stores, where the detail groups documenting sales for each department 
(one department per detail group) from the same store might be preceded by a 
control heading that states the full name and location of the store. 


Detail Group 
A report group that contains the detailed data being presented for the report. 


Page Footing 
A report group that appears at the bottom of every page of an RWCS-generated 
report. Information typically found within such a report group might be: 


15 January 2023 Chapter 9 - Report Writer Usage 


602 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


e The date the report was generated 
e The current page number of the report 
Page Heading 


A report group that appears at the top of every page of an RWCS-generated 
report. Information typically found within such a report group might be: 


e A title for the report 
e The date the report was generated 
e The current page number of the report 
e Column headings describing the fields within the detail group(s) 
Report Footing 
A report group that occurs only once in an RWCS-generated report — as the 


very last presented report group of the report. These typically serve as a visual 
indication that the report is finished. 


Report Group 
One or more consecutive lines on a report that serve a common informational 
purpose or function. For example, lines of text that are displayed at the top or 
bottom of every printed page of a report. 


Report Heading 
A report group that occurs only once in an RWCS-generated report — as the 
very first presented report group of the report. These typically serve as an 
introduction to the report. 


9.2. The Anatomy of a Report 


Every report has the same basic structure, as shown here, even though not all reports will 
have all of the groups shown. In fact, it is a very unusual report indeed that actually has 
every one of these groups: 


e REPORT HEADING 

e PAGE HEADING [1] 

e CONTROL HEADING(S) [2] 
e DETAIL GROUP(S) [2] 

e CONTROL FOOTING(S) [2] 
e FINAL CONTROL FOOTING 
e PAGE FOOTING [I] 

e REPORT FOOTING 


(1] Presented throughout the report, as needed 
[2] Repeated, as needed 


These groups will be presented (printed) across however many formatted pages are necessary 
to hold them. No single report group will be allowed to cross page boundaries. 
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The management of paging, enforcement of the groups cannot span pages rule and almost 
every aspect of report generation are handled entirely by the Report Writer Control System. 


9.3. The Anatomy of a Report Page 


Each page of a report is divided into as many as five (5) areas, as shown in the following 
diagram. 


| Top-of-page Unusable Area |—# Lines: LINES AT TOP (LINAGE) 

Ye een ee | 

| |—Line #: HEADING (RD) 

| Heading Area | 

ERO SOLS e ae ee nore |—Line #: FIRST DETAIL (RD) - 1 
|—Line #: FIRST DETAIL (RD) 
| 

Body Area |—Line #: LAST CONTROL HEADING (RD) 
|—Line #:: LAST DETAIL (RD) 

Pao Pe eet pate le Pak ae ee |—Line #: FOOTING (RD) 

| |—Line #: FOOTING (RD) + 1 


| Bottom-of-page Unusable Area |—+# Lines: LINES AT BOTTOM (LINAGE) 


When describing a report via the RD (see [REPORT SECTION], page 135) clause, the total 
number of usable lines are specified as the PAGE LIMIT value; this value is the sum of the 
number of lines contained in the Heading, Body and Footing Areas. 


The unusable areas of a page (if any) will appear above and below that usable area. 
You don’t specify the unusable area in the RD, but rather using a LINAGE (see [File/Sort- 
Description], page 124) clause in the FD of the file the report is “attached” to. 


The various report groups will be presentable in the various areas of a page, as follows: 


REPORT HEADING 
Heading Area — An exception to this is the situation where the report head- 
ing report group contains the NEXT GROUP NEXT PAGE (see [NEXT GROUP], 
page 187) option; in those cases, the report heading will be presented on a page 
by itself (anywhere on that page) at the beginning of the report. 


PAGE HEADING 
Heading Area 


CONTROL HEADING 
Body Area, but no line of a control heading is allowed past the line number 
specified by LAST CONTROL HEADING 
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DETAIL Body Area, but no line of a detail report group is allowed past the line number 
specified by LAST DETAIL 


CONTROL FOOTING 
Body Area, but no line of a control footing report group is allowed past the line 
number specified by FOOTING 


PAGE FOOTING 
Footing Area 


REPORT FOOTING 
Footing Area — An exception to this is the situation where the report footing 
report group contains the NEXT PAGE option in its LINE (see [LINE], page 183) 
clause; in those cases, the report footing will be presented on a page by itself 
at the end of the report. 


9.4. How RWCS Builds Report Pages 


A report created via a WRITE statement (see [WRITE], page 417) will contain carriage- 
control information. Most notably, ASCII form-feed characters (X’0C’) will be written 
to the report file to support the statement’s ADVANCING PAGE option. Whether the data 
for a report line created via ADVANCING PAGE occurs before or after the form-feed character 
depends upon whether the programmer coded WRITE record-name BEFORE ADVANCING PAGE 
or WRITE record-name AFTER ADVANCING PAGE, respectively. 

The GnuCOBOL implementation of RWCS does not issue any carriage-control infor- 
mation to the report files it produces — instead, it relies upon the information coded in 
the RD for the report (specifically the PAGE LIMITS and related options) and its internally- 
generated and managed LINE-COUNTER special register (see [Special Registers], page 265) 
for the report to know when to issue any blank lines to the file to fill-out the end of a printed 
page. 

Because this is the way the GnuCOBOL RWCS works, in order to design an RWCS5S- 
generated report you’ll need to know answers to the following questions: 

1. What printer(s) will the report be printed on? 

2. What paper orientation will you use, — Landscape (long edge of the paper at the top 
and bottom of page), or Portrait (long edge of the paper at the left and right of page)? 

3. What tool will be used to print the report (direct printing to the device, notepad.exe, 
MS-Word, ...)? 

4. What font and font size will be used for the report when it is printed? RWCS-generated 
reports will assume that a fixed-width font such as “Courier”, “Lucida Console”, “Con- 
solas” and the like will be used to print, as variable-pitch fonts would make the proper 
alignment of columns of data on reports virtually impossible. 

5. When unprintable area exists at all four margins of the paper? These are generally 
caused by the printer itself or by its software driver. 

6. What is the maximum number of lines per page that may be printed on a single sheet 
of paper? 

7. What is the maximum number of characters that may be printed on one line? 
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Once you know the answer to questions 1-4, you may easily determine the answers to the 
remaining questions as follows: 


1. Prepare a text file containing 100 or so records, each consisting of a numeric scale 
(123456789012345678901234. ..). 


2. Print the file in a manner consistent with your answers to questions 1-4. 


3. Add any necessary additional digits to each record in your test file (if lines weren’t 
full) or remove characters from the end of each record if lines wrapped. If you made 
changes, reprint the file. 

4. Now that you know ezactly how long each record may be, add additional records and 
reprint. Continue until printing overflows to a second page. 

5. The first page you print is now a perfect template to use when designing reports — it 
shows, given the answers to questions 1-4, every available printable character position 
on a page! The number of lines printed on that page becomes your PAGE LIMIT value 
for the RD. 


The remaining PAGE LIMIT values can be established as required by your report(s). 

Using identifier rather than integer specifications in the RD will give your program the 
ability — at run time — to accommodate multiple printers, fonts, font sizes and paper 
orientation. Just follow the above steps for each combination you wish your program to 
support. 


9.5. Control Hierarchy 


Every report that employs control breaks has a natural hierarchy of those control breaks 
based upon the manner in which the data the report is being generated from is sorted. This 
concept is best understood using an example which assumes a COBOL program to process 
sales data collected from every computerized cash register across a chain of stores having 
multiple departments is being developed. 


The application that collects data from the various cash registers at each store will 
generate data records that look like this to a COBOL program: 


O01 Sales-For-Register. 


05 Sales-Date PIC 9(8). 
05 Time-Collected PIC 9(6). 
05 Register-Number PIC 9(7). 
05 Store-Number PIC 9(3). 
05 Department-Number PIC 9(3). 
05 Total-Sales PIC 9(6)V99. 


Your task is to develop a report that shows the sales total from each cash register and 
summarizes those sales by department within each store, by store and also generates a total 
sales figure for the day across all stores. 

To accomplish this, you will use a SORT statement (see [SORT], page 391) to sort the 
file of cash register sales data into: 
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2. Within each store, data will be sorted into ascending sequence of department number 


3. If there are multiple cash registers in a particular department of a specific store, the 
data needs to be further sorted so that the cash registers are ordered in sequence of 
their register number. 


So, assuming a sort file has been defined and its record layout (essentially a mirror of 
the raw data file) is defined as follows: 


01 Sorted-Sales-For-Register. 


05 
05 
05 
05 
05 
05 


Then the SORT statement to accomplish the desired sequencing would be: 


Sorted-Sales-Date PIC 
Sorted-Time-Collected PIC 
Sorted-Register-Number PIC 
Sorted-Store-Number PIC 
Sorted-Department—Number PIC 
Sorted-Total-Sales PIC 


SORT SORT-FILE 


ASCENDING KEY Sorted-Store-Number 
Sorted-Department—Number 


Sorted-Register-Number 


USING Input-file 


OUTPUT PROCEDURE 100-Generate-Report 


9(8). 
9(6). 
OE 
9(3). 
9(3). 
9(6)V99. 


As a result of the sort, our program might expect to see data somewhat like this (date, time 


and sales totals are shown as 


9 


oe 


Register Number 


| t------------- Store Number 


.. .0535240001001... 
.. 0589130001001... 
...0625174001001... 
.. .0122234001002... 
. . .0732345001002... 
. . 0003423001003... 
.. . 2038774001004... 
...0112646002001... 
. . 9963348002002... 
.. -38245677002003... 
.. 4456778002003... 

. 0002345002004... 


Department Number 


Because of the sort, the most-frequently changing value of the three sort keys will be that 
of Sorted-Register-Number. This essentially defines the “detail” level of the report. 


Chapter 9 - Report Writer Usage 


15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 607 


The next most-frequently changing value is that of Sorted-Department-Number, and 
the least-frequently changing value is that of Sorted-Store-Number. remember that the 
program should be generating totals each time one of these two values change, plus a grand 
total of sales at the end of the report. These three points are the Control Break points of 
the report. 

When the report is defined, it’s RD would contain a CONTROLS ARE clause that lists the 
control breaks in least- to most-frequent sequence of changing. This would be coded as: 


CONTROLS ARE FINAL, Sorted-Store-Number, Sorted-Department-Number 


A FINAL control break only occurs once, at the very end of the report. The CONTROL 
FOOTING for this break will be the one that produces the grand total of sales for all stores. 


The next break listed on the CONTROLS clause will be the one that occurs next most- 
frequently (Sorted-Store-Number). This control break will be the one that produces the 
summation for each entire store, and will have its own CONTROL FOOTING. 


The next (and last, in this case) break listed on the CONTROLS clause will be the one that 
occurs even more frequently (Sorted-Department-Number). The CONTROL FOOTING for this 
control field will be the one that summarizes sales for each department within a store. 


This sequence of control breaks from least- to most-frequent (in other words, in the order 
they occur on the CONTROLS ARE clause) is the ’control hierarchy’ of the report; control 
breaks that occur more frequently than others are said to be at a lower level in the control 
hierarchy. 

Defining a control hierarchy (via CONTROLS ARE) that does not match the actual sequence 
in which data will be processed is a great way to guarantee a “broken” report. I'll show 
you an example in a later section. 


9.6. An Example 


This section contains an example of the RWCS at work. The complete program, presented 
here, is a stripped-down version of a program I have used to generate a report for a class 
I teach on PC hardware. This report will provide benchmark statistics on a variety of 
popular AMD and Intel CPUs. The data for the report was obtained from the website www. 
cpubenchmark.net in December of 2013. By the time you are reading this, that data will 
most likely have become rather out of date, but it illustrates RWCS well enough. 


9.6.1. Data 


Here is the data that the program will be reading. Each record reflects the aggregated 
benchmark scoring for one particular CPU, as scores for benchmarks against that CPU have 
been reported to the cpubenchmark.net website by their PassMark benchmark software. 
The data consists of four fields. Fields are separated from one another by a single comma. 
The descriptions of the fields are as follows: 


Benchmark Score 
A five-digit number showing the aggregated benchmark scores for the CPU; the 
higher this number, the better the CPU performed in benchmark testing. 
Vendor The name of the vendor who makes the CPU. In this data, that will either be 
“AMD” (American Micro Devices) or “INTEL”. 
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Family The 7-character family of CPU products the CPU falls into. This will have 
values such as “A4”, “A10”, “Core i5”, “Core i7”, etc. 
Model The specific model of CPU within the family. 


The first record of data shown below shows that the aggregated score of all benchmarks 
reported for the AMD A10-4600M CPU is 3145, as compared to the second record which 
shows that the aggregated score reported of all benchmarks reported for the Intel Core-i7- 
4960X CPU is 14291. 


The following is the complete set of input data used for this example. This is by no 
means the complete set of data available at cpubenchmark.net — it is just a representative 
sample used for this example. For my class, I give my students a report showing the results 
for almost a thousand CPUs. 


For the sake of brevity, this document lists the data in three columns. 


03145, AMD ,A10,4600M 05421, AMD ,FX,6100 03917,Intel,Core i5,4300U 
14291 ,Intel,Core i7,4960X 05813, AMD ,FX,6120 01743,Intel,Core i5,4300Y 
02505, AMD, A10,4655M 06194, AMD ,FX,6200 04804,Intel,Core i5,4330M 
03449, AMD ,A10,4657M 06388 , AMD , FX,6300 03604,Intel,Core i5,4350U 
04251, AMD,A10,5700 07017, AMD ,FX,6350 06282,Intel,Core i5,4430 
02758, AMD ,A10,5745M 06163, AMD ,FX,8100 05954,Intel,Core i5,44305 
03332, AMD ,A10,5750M 06605, AMD ,FX,8120 06517, Intel,Core i5,4440 
03253, AMD,A10,5757M 06845 , AMD ,FX,8140 07061,Intel,Core i5,4570 
04798, AMD ,A10,5800B 07719, AMD ,FX,8150 06474,Intel,Core i5,4570R 
04677 , AMD ,A10,5800K 08131, AMD ,FX,8320 06803, Intel,Core i5,45705 
04767 , AMD ,A10,6700 09067 , AMD ,FX,8350 02503, Intel,Core i5,4570T 
05062, AMD ,A10,6800K 09807 , AMD ,FX,9370 07492,Intel,Core i5,4670 


00677 , AMD ,A4,1200 10479, AMD , FX, 9590 07565,Intel,Core i5,4670K 
00559, AMD ,A4,1250 03076,Intel,Core i3,3110M 06351,Intel,Core i5,4670T 
01583, AMD, A4,3300 03301,Intel,Core i3,3120M 03701,Intel,Core i7,3517U 


01237, AMD , A4,3300M 
01227, AMD, A4,3305M 
01263, AMD ,A4,3310MX 
01193, AMD, A4,3320M 
01343, AMD, A4,3330MX 
01625, AMD, A4,3400 
01768, AMD ,A4,3420 
01685, AMD, A4,4300M 
01169, AMD, A4,4355M 
01919, AMD ,A4,5000 
01973, AMD, A4,5150M 
02078, AMD ,A4,5300 
01632, AMD ,A4,5300B 
02305, AMD ,A4,6300 
01634, AMD ,A6,1450 
01964, AMD, A6,3400M 
02101, AMD ,A6,3410MX 
02078, AMD, A6 ,3420M 
02277 , AMD , A6 ,3430MX 


03655,Intel,Core i3,3130M 
03820,Intel,Core 13,3210 
02266,Intel,Core i3,3217U 
04219,Intel,Core 13,3220 
03724 ,Intel,Core i3,3220T 
04407 ,Intel,Core 13,3225 
02575,Intel,Core i3,3227U 
01885,Intel,Core i3,3229Y 
04259, Intel,Core i3,3240 
03793,Intel,Core i3,3240T 
04414,Intel,Core 13,3245 
04757 ,Intel,Core i3,3250 
03443 ,Intel,Core i3,4000M 
02459, Intel,Core i3,4010U 
02003, Intel,Core i3,4010Y 
04904,Intel,Core i3,4130 
04041,Intel,Core i3,4130T 
05115,Intel,Core i3,4330 
05117, Intel,Core i3,4340 


03449 ,Intel,Core i7,3517UE 
04588, Intel,Core i7,3520M 
03912,Intel,Core i7,3537U 
04861,Intel,Core i7,3540M 
04009, Intel,Core i7,3555LE 
06144,Intel,Core i7,3610QE 
07532,Intel,Core i7,3610QM 
06988, Intel,Core i7,3612QE 
06907, Intel,Core i7,3612QM 
05495, Intel,Core i7,3615QE 
07310,Intel,Core i7,3615QM 
07759,Intel,Core i7,3630QM 
07055,Intel,Core i7,3632QM 
06516,Intel,Core i7,3635QM 
04032,Intel,Core i7,3667U 
04271,Intel,Core i7,3687U 
03479,Intel,Core i7,3689Y 
08347 ,Intel,Core i7,3720QM 
08512, Intel,Core i7,3740QM 


01995, AMD, A6,3500 03807 ,Intel,Core i5,3210M 09420,Intel,Core i7,3770 
02798, AMD , A6 ,3600 03995,Intel,Core i5,3230M 09578,Intel,Core i7,3770K 
02892, AMD , A6,3620 03126,Intel,Core i5,3317U 09074,Intel,Core i7,37705 
03232, AMD ,A6,3650 04101,Intel,Core i5,3320M 08280,Intel,Core i7,3770T 
03327 , AMD ,A6,3670 05902,Intel,Core i5,3330 08995,Intel,Core i7,3820 
01630, AMD, A6,4400M 05690,Intel,Core i5,33305 08548, Intel,Core i7,3820QM 
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01296, AMD, A6,4455M 


02440, AMD , A6,5200 


01958, AMD , A6,5350M 
01878, AMD, A6,5357M 
01906, AMD, A6 ,5400B 
02174, AMD, A6,5400K 
02384, AMD , A6 ,6400K 
02050, AMD , A8,3500M 
02426, AMD, A8,3510MX 
02245 , AMD, A8,3520M 
02276, AMD, A8,3530MX 
02866, AMD ,A8,3550MX 


03215, AMD,A8,3800 
03217, AMD, A8,3820 
03552, AMD, A8,3850 


03682, AMD, A8,3870K 
02709, AMD , A8,4500M 
02193, AMD ,A8,4555M 


04052, AMD ,A8,5500 


03464, AMD ,A8,5500B 
02434, AMD, A8,5545M 
03052, AMD, A8,5550M 
02935, AMD,A8,5557M 
04348 , AMD , A8,5600K 


04390, AMD, A8,6500 


04719, AMD ,A8,6600K 


04055, AMD , FX, 4100 
04153, AMD ,FX,4130 
04094, AMD ,FX,4150 
04774, AMD ,FX,4170 
04711, AMD ,FX,4300 
05247 , AMD ,FX,4350 


9.6.2. Program 


05781,Intel,Core 
03280 ,Intel,Core 
02252,Intel,Core 
06282,Intel,Core 
04327 , Intel ,Core 
05372,Intel,Core 
06199, Intel,Core 
04314,Intel,Core 
04555, Intel,Core 
03589, Intel,Core 
03479, Intel,Core 
03057, Intel ,Core 
06442 ,Intel,Core 
06071,Intel,Core 
06576, Intel,Core 
06077, Intel,Core 
04591 ,Intel,Core 
05991,Intel,Core 
06828 ,Intel,Core 
06631,Intel,Core 
06993, Intel,Core 
07118,Intel,Core 
06709, Intel ,Core 
05414, Intel,Core 
04333,Intel,Core 
03355 ,Intel,Core 
02358, Intel ,Core 
02382,Intel,Core 
03482 ,Intel,Core 
04381 ,Intel,Core 
04663, Intel,Core 
04786, Intel,Core 


15,3335S 
15,3337U 
15,3339Y 
15,3340 

15,3340M 
15,3340S 
15,3350P 
15,3360M 
15,3380M 
15,3427U 
15,3437U 
15,3439Y 
15,3450 

15,3450S 
15,3470 

15,3470S 
15,3470T 
15,3475S 
15,3550 

15,35508 
15,3570 

15,3570K 
15,3570S 
15,3570T 
1i5,4200M 
1i5,4200U 
15,4200Y 
15,4210Y 
15,4250U 
15 ,4258U 
15 ,4288U 
15,4300M 


09025, Intel,Core 
09196,Intel,Core 
12107, Intel,Core 
09052, Intel,Core 
12718, Intel,Core 
12823, Intel,Core 
03992, Intel,Core 
04507, Intel,Core 
04892,Intel,Core 
04484, Intel,Core 
03680, Intel ,Core 
04345 ,Intel,Core 
07352, Intel,Core 
08161,Intel,Core 
07946, Intel,Core 
08002, Intel,Core 
07647, Intel,Core 
08066, Intel ,Core 
07367, Intel,Core 
09969,Intel,Core 
10190, Intel,Core 
09803, Intel,Core 
08803, Intel,Core 
10078, Intel,Core 
08567, Intel,Core 
09969, Intel,Core 
09331,Intel,Core 
09323,Intel,Core 
13620, Intel,Core 
09754, Intel,Core 
10262, Intel,Core 


17 ,3840QM 
17 ,3920XM 
17 ,3930K 
17 ,3940XM 
1i7,3960X 
i7,3970X 
i7,4500U 
i7,4558U 
i7,4600M 
i7,4600U 
i7,4610Y 
1i7,4650U 
i7,4700EQ 
i7,4700HQ 
i7,4700MQ 
i7,4702HQ 
i7,4702MQ 
i7,4750HQ 
i7,4765T 
17,4770 

i7,4770K 
1i7,47708 

i7,4770T 
17,4771 

i7,4800MQ 
17 ,4820K 
i7,4850HQ 
i7,4900MQ 
17 ,4930K 
17 ,4930MX 
i7,4960HQ 
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Here is the program that will be producing the report. Pay attention to how the data is 
sorted and how the control hierarchy (CONTROLS ARE) relates to the SORT. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEMORWCS. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
REPOSITORY. FUNCTION ALL INTRINSIC. 
INPUT-OUTPUT SECTION. 


FILE-CONTROL. 


SELECT CPU-FILE 


SELECT REPORT-FILE 


SELECT SORT-FILE 


DATA DIVISION. 
FILE SECTION. 
FD CPU-FILE. 


15 January 2023 


ASSIGN TO 
LINE SEQUENTIAL. 


ASSIGN TO 


"CPUDATA.txt" 


"CPUREPORT.txt" 


LINE SEQUENTIAL. 
ASSIGN TO DISK. 
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01 CPU-REC PIC X(26). 


FD REPORT-FILE 
REPORT IS CPU-Report. 


SD SORT-FILE. 


01 SORT-REC. 
05 F-SR-Score-NUM PIC 9(5). 
05 F-SR-Vendor-TXT PIC X(5). 
05 F-SR-Family-TXT PIC X(7). 
05 F-SR-Model-TXT PIC X(6). 

WORKING-STORAGE SECTION. 

01 WS-Date PIC 9(8). 


01 WS-Family-Counters. 


05 WS-FC-AVE PIC 9(5)V99. 
05 WS-FC-Qty BINARY-LONG. 
05 WS-FC-Total-NUM BINARY-LONG. 
01 WS-Flags. 
05 WS-F-EOF PIC X(1). 
01 WS-One-Const PIC 9 VALUE 1. 


01 WS-Overall-Counters. 


05 WS-OC-AVE PIC 9(5)V99. 
05 WS-OC-Qty BINARY-LONG. 
05 WS-OC-Total-NUM BINARY-LONG. 
01 WS-Starz PIC X(44) VALUE ALL ’*?’. 


01 WS-Vendor-Counters. 


05 WS-VC-AVE PIC 9(5)V99. 
05 WS-VC-Qty BINARY-LONG. 
05 WS-VC-Total-NUM BINARY-LONG. 


REPORT SECTION. 
RD CPU-Report 
CONTROLS ARE FINAL 
F-SR-Vendor-TXT 
F-SR-Family-TXT 


PAGE LIMIT IS 36 LINES 
HEADING 1 
FIRST DETAIL 5 
LAST DETAIL 36. 
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O1 TYPE IS PAGE HEADING. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Date PIC 9999/99/99. 
10 COL 14 VALUE ’CPU Benchmark Scores’. 
10 COL 37 VALUE ’Page:’. 


10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 


05 LINE NUMBER PLUS 1. 
10 COL 1 VALUE ’**’. 
10 COL 6 VALUE ’All CPU Data From cpubenchmark.net’. 
10 COL 43 VALUE ’**’. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 


01 TYPE CONTROL HEADING F-SR-Family-TXT. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE F-SR-Vendor-TXT PIC X(6). 
10 COL 8 SOURCE F-SR-Family-TXT PIC X(7). 
05 LINE NUMBER PLUS 1. 
10 COL 1 VALUE ’Family’. 
10 COL 9 VALUE ’Model’. 
10 COL 16 VALUE ’Benchmark Score (High to Low)’. 
05 LINE NUMBER PLUS 1. 
10 COL 1 VALUE ?======’, 
10 COL 9 VALUE ’?======?, 
10. COL-16: VALUE? ==========SSSSSSSSSSSSSSRSSS=7 « 


01 Detail-Line TYPE IS DETAIL. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE F-SR-Family-TXT PIC X(7) GROUP INDICATE. 
10 COL 9 PIC X(6) SOURCE F-SR-Model-TXT. 
10 COL 16 PIC ZZZZ9 SOURCE F-SR-Score-NUM. 


01 End-Family TYPE IS CONTROL FOOTING F-SR-Family-TXT. 
05 LINE NUMBER PLUS 1. 


10 COL 9 VALUE ’Ave...’. 

10 COL 16 PIC ZZZZ9.99 SOURCE WS-FC-AVE. 

10 COL 25 VALUE ’(?. 

10 COL 26 PIC ZZ9 SUM WS-One-Const. 
10 COL 30 VALUE ’Family CPUs)’. 


01 End-Vendor TYPE IS CONTROL FOOTING F-SR-Vendor-TXT. 
05 LINE NUMBER PLUS 1. 
10 COL 9 VALUE ’Ave...’. 


15 January 2023 Chapter 9 - Report Writer Usage 


612 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


10 COL 16 PIC ZZZZ9.99 SOURCE WS-VC-AVE. 


10 COL 25 VALUE ’(?. 
10 COL 26 PIC ZZ9 SUM WS-One-Const. 
10 COL 30 VALUE ’Vendor CPUs)’. 


01 End-Overall TYPE IS CONTROL FOOTING FINAL. 
05 LINE NUMBER PLUS 1. 


10 COL 9 VALUE ’Ave...’. 

10 COL 16 PIC ZZZZ9.99 SOURCE WS-OC-AVE. 

10 COL 25 VALUE ’(?. 

10 COL 26 PIC ZZ9 SUM WS-One-Const. 
10 COL 30 VALUE ’CPUs)’. 


PROCEDURE DIVISION. 
DECLARATIVES. 
000-End-Family SECTION. 
USE BEFORE REPORTING End-Family. 
1. IF WS-FC-Qty > 0 
COMPUTE WS-FC-AVE = WS-FC-Total-NUM / WS-FC-Qty 
ELSE 
MOVE 0 TO WS-FC-AVE 
END-IF 
MOVE 0 TO WS-FC-Qty 
WS-FC-Total-NUM 


000-End-Vendor SECTION. 
USE BEFORE REPORTING End-Vendor. 
1. IF WS-VC-Qty > 0 
COMPUTE WS-VC-AVE = WS-VC-Total-NUM / WS-VC-Qty 
ELSE 
MOVE 0 TO WS-VC-AVE 
END-IF 
MOVE 0 TO WS-VC-Qty 
WS-VC-Total-NUM 


000-End-Overall SECTION. 
USE BEFORE REPORTING End-Overall. 
1. IF WS-OC-Qty > 0 
COMPUTE WS-OC-AVE = WS-OC-Total-NUM / WS-OC-Qty 
ELSE 
MOVE O TO WS-OC-AVE 
END-IF 
MOVE O TO WS-OC-Qty 
WS-OC-Total-NUM 


END DECLARATIVES . 
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010-Main SECTION. 


ale 


ACCEPT WS-Date FROM DATE YYYYMMDD 
SORT SORT-FILE 
ASCENDING KEY F-SR-Vendor-TXT 
F-SR-Family-TXT 
DESCENDING KEY F-SR-Score-NUM 
ASCENDING KEY F-SR-Model-TXT 
INPUT PROCEDURE 100-Pre-Process-Data 
OUTPUT PROCEDURE 200-Generate-Report 
STOP RUN 


100-Pre-Process-Data SECTION. 


1. 


OPEN INPUT CPU-FILE 
PERFORM FOREVER 
READ CPU-FILE 
AT END 
EXIT PERFORM 
END-READ 
MOVE SPACES TO SORT-REC 
UNSTRING CPU-REC DELIMITED BY ’,’ 
INTO F-SR-Score-NUM, 
F-SR-Vendor-TxT, 
F-SR-Family-TXT, 
F-SR-Model-TXT 
RELEASE SORT-REC 
END-PERFORM 
CLOSE CPU-FILE 


200-Generate-Report SECTION. 


1. 


15 January 2023 


INITIALIZE WS-Family-Counters 
WS-Flags 
OPEN OUTPUT REPORT-FILE 
INITIATE CPU-Report 
RETURN SORT-FILE 
AT END 
MOVE ’Y’ TO WS-F-EOF 
END-RETURN 
PERFORM UNTIL WS-F-EOF = ’Y’ 
GENERATE Detail-Line 
ADD 1 TO WS-FC-Qty 
WS-OC-Qty 
WS-VC-Qty 
ADD F-SR-Score-NUM TO WS-FC-Total-NUM 
WS-OC-Total-NUM 
WS-VC-Total-NUM 


613 


Chapter 9 - Report Writer Usage 


614 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


RETURN SORT-FILE 
AT END 
MOVE ’Y’ TO WS-F-EOF 
END-RETURN 
END-PERFORM 
TERMINATE CPU-Report 
CLOSE REPORT-FILE 


9.6.3. Generated Report Pages 


Finally, here’s the report the program generates! 


2013/12/24 CPU Benchmark Scores Page: 1 
FEA AAA AAR CI I I I I I Ik 2k 2k 2k 2k 2k 2k 2k 2k 
** All CPU Data From cpubenchmark.net ** 
FEA AAA AA AOR CI I I I I I IK 2k 2k 24 24 2k 2k 2k 
AMD A10 

Family Model Benchmark Score (High to Low) 


A10 6800K 5062 
5800B 4798 
6700 A767 
5800K 4677 
5700 4251 
4657M 3449 
5750M 3332 
5757M 3253 
4600M 3145 
5745M 2758 
A4655M 2505 
Ave... 3817.90 ( 11 Family CPUs) 

AMD A4 


Family Model Benchmark Score (High to Low) 


A4 6300 2305 
5300 2078 
5150M 1973 
5000 1919 
3420 1768 
4300M 1685 
5300B 1632 
3400 1625 
3300 1583 


3330MX 1343 
3310MX 1263 
3300M 1237 
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3305M 1227 
3320M 1193 


2013/12/24 CPU Benchmark Scores Page: 2 
FEAR CI A I I I I IK 1 21 24 24 2k 2k 2k 2k 
** All CPU Data From cpubenchmark.net ** 
FEA AAA AAO CC AI I I I I KK 2k 21 24 2k 2k 2k 2k 


A4 4355M 1169 

1200 677 

1250 559 

Ave... 1484.47 ( 17 Family CPUs) 
AMD A6 


Family Model Benchmark Score (High to Low) 


AG 3670 3327 
3650 3232 
3620 2892 
3600 2798 
5200 2440 
6400K 2384 
3430MX 2277 
5400K 2174 
3410MX 2104 
3420M 2078 
3500 1995 
3400M 1964 
5350M 1958 
5400B 1906 
5357M 1878 
1450 1634 
4400M 1630 
4455M 1296 
Ave... 2220.22 ( 18 Family CPUs) 

AMD AB 


Family Model Benchmark Score (High to Low) 


A8 6600K 4719 
6500 4390 
5600K 4348 


2013/12/24 CPU Benchmark Scores Page: 3 
BOAO AOA RRA AC IA KK 


** All CPU Data From cpubenchmark.net ** 
FRAGA AA AOR CI I I I I IK 21 21 2k 24 2k 2k 2k 2k 
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A8 5500 4052 
3870K 3682 
3850 3552 
5500B 3464 
3820 3217 
3800 3215 
5550M 3052 
S557M =. 2935 
3550MX 2866 
4500M 2709 
5545M = 2434 


3510MX 2426 
3530MX 2276 


3520M 2245 

A555M 2193 

3500M 2050 

Ave... 3148.68 ( 19 Family CPUs) 
AMD FX 


Family Model Benchmark Score (High to Low) 


FX 9590 10479 
9370 9807 
8350 9067 
8320 8131 
8150 7719 
6350 7017 
8140 6845 
8120 6605 
6300 6388 
6200 6194 
8100 6163 
6120 5813 


2013/12/24 CPU Benchmark Scores Page: 4 
BOBO OKO AFORE 


** All CPU Data From cpubenchmark.net ** 
FEA AAA ORR CII I I I I I kk 2k 2k 24 2k 2k 2k 2k 


FX 6100 5421 
4350 5247 
4170 A774 
4300 4711 
4130 4153 
4150 4094 
4100 4055 
Ave... 6457.00 ( 19 Family CPUs) 
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Ave... 3448.86 ( 84 Vendor CPUs) 
Intel Core i3 
Family Model Benchmark Score (High to Low) 


Core i3 4340 5117 


4330 5115 
4130 4904 
3250 4757 
3245 4414 
3225 4407 
3240 4259 
3220 4219 
4130T 4041 
3210 3820 
3240T 3793 
3220T 3724 
3130M 3655 
4000M 3443 
3120M 3301 
3110M 3076 
3227U =. 2575 
4010U) 2459 
3217U = 2266 
4010Y 2003 


2013/12/24 CPU Benchmark Scores Page: 5 
FEA AAA AA AOR CI II I I I I kK 2k 2k 21 2k 2k 2k 2k 
*K All CPU Data From cpubenchmark.net > 
FEA AAA ARR CC I I I I I KK 2k 2k 24 24 2k 2k 2k 
Core i3 3229Y 1885 
Ave... 3677.76 ( 21 Family CPUs) 

Intel Core id 

Family Model Benchmark Score (High to Low) 


Core i5 4670K 7565 


4670 7492 
3570K 7118 
4570 7061 
3570 6993 
3550 6828 
4570S 6803 
3570S 6709 
35505 6631 
3470 6576 
4440 6517 
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4570R 6474 
3450 6442 
4670T 6351 
3340 6282 
4430 6282 
3350P 6199 
3470S 6077 
34505 6071 
34755 5991 
4430S 5954 
3330 5902 
33355 5781 
33305 5690 
3570T 5414 
3340S 5372 
4330M 4804 


2013/12/24 CPU Benchmark Scores Page: 6 
FEA AAA AAR CC I I I I I IK 21 2k 2k 24 24 2k 2k 2k 
** All CPU Data From cpubenchmark.net ** 
FEA AAA AA ORR CCI I I I I I IK 1 21 24 24 2k 2k 2k 2k 
Core i5 4300M 4786 


4288U 4663 
3470T 4591 
3380M 4555 
4258U 4381 
4200M 4333 
3340M 4327 
3360M 4314 
3320M 4101 
3230M 3995 
4300U 3917 
3210M 3807 
4350U 3604 
3427U = 3589 
4250U 3482 
3437U =. 34779 
4200U 3355 
3337U 3280 
3317U = 3126 
3439Y 3057 
4570T 2503 
A210Y 2382 
4200Y 2358 
3339Y 2252 
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4300Y 1743 

Ave... 5026.13 ( 52 Family CPUs) 
Intel Core i7 
Family Model Benchmark Score (High to Low) 


Core i7 4960X 14291 
4930K 13620 
3970X 12823 


2013/12/24 CPU Benchmark Scores Page: 7 
FERC RG OR GA RCA A A RK A aK KK A 6 2k 2k 
*K All CPU Data From cpubenchmark.net xk 
FEC OA GR GA OR AR AR RR A aK Kk A a 2k 2k 
Core i7 3960X 12718 

3930K 12107 

4960HQ 10262 

4770K 10190 


4771 10078 
4770 9969 
4820K 9969 
4770S 9803 
4930MX 9754 
3770K 9578 
3770 9420 


4850HQ 9331 
4900MQ 9323 
3920XM 9196 
37705 9074 
3940XM 9052 
3840QM 9025 
3820 8995 
4770T 8803 
4800MQ 8567 
3820QM 8548 
3740QM 8512 
3720QM 8347 
3770T 8280 
4700HQ 8161 
4750HQ 8066 
4702HQ 8002 
4700MQ 7946 
3630QM 7759 
4702MQ 7647 
3610QM 7532 
4765T 7367 
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2013/12/24 CPU Benchmark Scores Page: 8 
FEO OO OR KK 
** All CPU Data From cpubenchmark.net *K 
FEO OO OR RK KK 
Core i7 4700EQ 7352 

3615QM 7310 

3632QM 7055 

3612QE 6988 

3612QM 6907 

3635QM 6516 

3610QE 6144 

3615QE 5495 


4600M 4892 

3540M 4861 

3520M 4588 

4558U 4507 

4600U 4484 

4650U 4345 

3687U 4271 

3667U 4032 

3555LE 4009 

4500U 3992 

3537U = 33912 

3517U = 3701 

4610Y 3680 

3689Y 3479 

3517UE 3449 

Ave... 7725.58 ( 58 Family CPUs) 
Ave... 6005.16 (131 Vendor CPUs) 
Ave... 5006.42 (215 CPUs) 


9.7. Control Hierarchy (Revisited) 


The sample program just discussed presents a great opportunity to show what can happen 
if you don’t define the control hierarchy of a report properly. 


I changed the CONTROLS ARE clause on the sample program from this: 


CONTROLS ARE FINAL 
F-SR-Vendor-TXT 
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F-SR-Family-TXT 


To this: 


CONTROLS ARE FINAL 
F-SR-Family-TXT 
F-SR-Vendor-TXT 


And then ran the report again. Here are the first two pages of that new report. See what 
happened to the control breaks? 

2013/12/24 CPU Benchmark Scores Page: 1 

FASCIA IORI ICICI A II I A kak a 

** All CPU Data From cpubenchmark.net ** 

FEAR I OIA IIRC A I I I A kak ak 

AMD A10 

Family Model Benchmark Score (High to Low) 


A10 6800K 5062 

5800B 4798 

6700 4767 

5800K 4677 

5700 4251 

4657M 3449 

5750M 3332 

5757M 3253 

4600M 3145 

5745M 2758 

4655M 2505 

Ave... 3817.90 ( 11 Vendor CPUs) 

Ave... 3817.90 ( 11 Family CPUs) 
AMD A4 


Family Model Benchmark Score (High to Low) 


A4 6300 2305 
5300 2078 
5150M 1973 
5000 1919 
3420 1768 
4300M 1685 
5300B 1632 
3400 1625 
3300 1583 


3330MX 1343 
3310MX 1263 
3300M 1237 
3305M 1227 
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2013/12/24 CPU Benchmark Scores Page: 2 
FEA AAA AAR CC I I I I IK I 21 24 2k 2k 2k 2k 2k 
** All CPU Data From cpubenchmark.net ** 
FEA AAA AAA CI I I I I I Ik 2k 2k 24 24 2k 2k 2k 2k 


A4 3320M 1193 
4355M 1169 
1200 677 
1250 559 
Ave... 1484.47 ( 17 Vendor CPUs) 
Ave... 1484.47 ( 17 Family CPUs) 
AMD A6 


Family Model Benchmark Score (High to Low) 


A6 3670 Boot 
3650 3232 
3620 2892 
3600 2798 
5200 2440 
6400K 2384 
3430MX 2277 
5400K 2174 
3410MX 2101 
3420M 2078 
3500 1995 
3400M 1964 
5350M 1958 
5400B 1906 
5357M 1878 
1450 1634 
4400M 1630 
4455M 1296 
Ave... 2220.22 ( 18 Vendor CPUs) 
Ave... 2220.22 ( 18 Family CPUs) 

AMD A8 


Family Model Benchmark Score (High to Low) 
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9.8. Turning PHYSICAL Page Formatting Into LOGICAL 
Formatting 


You can trick RWCS into using the PAGE LIMIT values as logical specifications rather than 
physical ones quite easily — simply include an ASCII form-feed (X’0C’) character into 
your page heading design! Here’s how the sample program shown earlier could be easily 
modified: 


Simply Change This... 


01 TYPE IS PAGE HEADING. 
05 LINE NUMBER 1. 
10 COL 1 SOURCE WS-Date PIC 9999/99/99. 
10 COL 14 VALUE ’CPU Benchmark Scores’. 
10 COL 37 VALUE ’Page:’. 
10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 
05 LINE NUMBER PLUS 1. 
10 COL 1 VALUE ’**’. 
10 COL 6 VALUE ’Al1l1 CPU Data From ’ & 
>cpubenchmark.net’. 
10 COL 43 VALUE ’**’. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 


To This... 
O01 TYPE IS PAGE HEADING. 
05 LINE NUMBER 1. *> NEW 
10 COL 1 VALUE X°’0C’. *> NEW 
05 LINE NUMBER PLUS 1. *> CHANGED 


10 COL 1 SOURCE WS-Date PIC 9999/99/99. 
10 COL 14 VALUE ’CPU Benchmark Scores’. 
10 COL 37 VALUE ’Page:’. 
10 COL 43 SOURCE PAGE-COUNTER PIC Z9. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 
05 LINE NUMBER PLUS 1. 
10 COL 1 VALUE ’**’. 
10 COL 6 VALUE ’All1 CPU Data From ’ & 
>cpubenchmark.net’. 
10 COL 43 VALUE ’**’. 
05 LINE NUMBER PLUS 1. 
10 COL 1 SOURCE WS-Starz PIC X(44). 


RWCS will still be counting lines to decide when to close off one page and start a new 
one, but when a new page is started its page heading will physically form-feed the printer 
when the report is printed. As long as any printer you plan on using supports at least as 
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many physical print lines as what is defined as the PAGE LIMIT value in whatever paper 
orientation and font you plan on (or are limited to) printing in, you have now divorced your 
program from the physical realities of the printer! 


Of course, whatever software you are using to deliver the printed document to the printer 
with, must allow the ASCII form-feed character to pass through to the printer. 


End of Chapter 9 — Report Writer Usage 
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10. Interfacing With The OS 


10.1. Compiling Programs 


Program source files should have by convention, extensions of .cob or .cbl. 


Program file names should match exactly the specification of PROGRAM-ID (including 
case). 


Spaces cannot be included in primary entry-point names and therefore must not be 
included in program file names. 


The GnuCOBOL compiler will translate your COBOL program into C source code, 
compile that C source code into executable binary form using the C compiler specified 
when GnuCOBOL was built and link that executable binary into: 


Directly executable form 
This is an executable file directly-executable from the command-line. On Win- 
dows computers, this would be an .exe file. On Unix systems, this will be a file 
with no specific extension, but with execute permissions. This file will include 
the main program as well as any static-linked subprograms. 


Static-linkable form 
This is a single subprogram compiled into object-code form, ready to be linked 
in with a main program to form a directly-executable program. On windows 
computers, these generally are .o (object-code) files. 


Dynamically-loadable executable form 
These are dynamically-loadable object code files ready to be invoked from other 
programs at execution time. On Windows systems, these would be .d11 files, 
while on Unix systems they are typically .so files (OSX uses .dylib). 


10.1.1. cobc - The GnuCOBOL Compiler - Runtime options 


The GnuCOBOL compiler is named cobc (cobc.exe on a Windows system). 


The following describes the syntax and option switches of the cobc command. This 
information may be displayed by entering the command cobc --help or cobc —h. 


GnuCOBOL compiler for most COBOL dialects with lots of extensions 


Sorted within groups 


Usage: cobc [options]... file... 
Options: 
-h, --help display this help and exit 
-du(mpversion) display compiler version and exit 
-i, --info display compiler information (build/environment) 
and exit 
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-q, --brief 
-vV, --verbose 
-V, --version 
-### 


-A <options> 


-b 

-Cc 
--conf=<file> 
-C 

-d, --debug 


-D <define> 

-ext <extension> 
-E 

-F, --free 
--fixed 


-fec=<exception-name> 
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reduced displays, commands invoked not shown 
verbose mode, display additional information; 
multiple -v options increase the verbosity, 
the maximum is 3 as follows: 

(1) display compiler version and the commands 
invoked by the compiler, 

(2) pass verbose option to assembler/compiler 
(3) pass verbose option to linker 

display compiler version information and exit 
like -v but commands not executed 


add <options> to the C compile phase 

combine all input files into a single 
dynamically loadable module 

compile and assemble, but do not link 
user-defined dialect configuration; see -std 
translation only; convert COBOL to C 

enable all run-time error checking, 

equal to -fstack-check -fec=EC-ALL 

define <define> for COBOL compilation 

add file extension for resolving COPY 
preprocess only; do not compile or link 

use free source format (alias for -fformat=free) 
use fixed source format (default; alias for 
-fformat=fixed) 

enable code generation for <exception-name>, 
see --list-exceptions for the possible values, 
sets -fsource-location 


-fno-ec=<exception-name> 


am 
-I <directory> 


disable code generation for <exception-name> 
enable C compiler debug and stack check 
add <directory> to copy/include search path 


-j [<args>], --job[=<args>] 


-K <entry> 

-1 <lib> 

-L <directory> 
--list-exceptions 
--list-intrinsics 
--list-mnemonics 
--list-reserved 
--list-system 

—m 

-o <file> 

-0, -02, -03, -Os 
-00 
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run program after build, passing <args> 
generate CALL to <entry> as static 

link the library <lib> 

add <directory> to library search path 
display exception names 

display intrinsic functions 

display mnemonic names 

display reserved words 

display system routines 

build a dynamically loadable module (default) 
place the output into <file> 

enable optimization 

disable optimization 
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-P[=<dir or file>] 
-Q <options> 
-std=<dialect> 


-S 
--save-temps [=<dir>] 


-t <file> 
--tlines=<lines> 
-T <file> 

-x 


-X, --Xref 


Warning options: 


-w 
-Wall 
-Wadditional 
-Warchaic 
-Warithmetic-osvs 
-Wcall-params 


-Wcolumn-overflow 


-Wconstant-expression 
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generate preprocessed program listing (.1lst) 

add <options> to the C link phase 
warnings/features for a specific dialect 
<dialect> can be one of: 

default, cobol2014, cobol2002, cobol85, xopen, 
ibm-strict, ibm, mvs-strict, mvs, 

mf-strict, mf, bs2000-strict, bs2000, 
acu-strict, acu, rm-strict, rm, gcos-strict, 
COS; 

see configuration files in directory config 
compile only; output assembly file 

save intermediate files 

* default: current directory 

generate and place a program listing into <file> 
specify lines per page in listing, default = 55 
generate and place a wide program listing into <file> 
build an executable program 

generate internal cross reference 


disable all warnings 

enable most warnings (all except as noted below) 
additional warnings only raised with -Wall 

warn if archaic features are used 

warn if arithmetic expression precision has changed 
warn about non 01/77 items for CALL parameters 

* NOT set with -Wall 

warn about text after program-text area, FIXED format 

* NOT set with -Wall 

warn about expressions that always resolve to true/false 


-Wconstant-numlit-expression 


-Wdangling-text 


-Werror 
-Werror=<warning> 
-Wextra 
-Wimplicit-define 
-Winitial-value 
-Wlarger-01-redefines 


-Wlinkage 


-Wobsolete 
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warn about numeric expressions that always resolve to 
true/false 

warn about source text after program-area 

* NOT set with -Wall 

treat all warnings as errors 

treat specified <warning> as error 

like -Wall but enable some extra warning flags 

warn whenever data items are implicitly defined 

* NOT set with -Wall 

warn if initial VALUE clause is ignored 

warn about larger redefines allowed by COBOL standards 
warn about dangling LINKAGE items 

* NOT set with -Wall 

warn if obsolete features are used 
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-Woverlap 
-Wno-corresponding 


-Wno-dialect 


warn about overlapping MOVE of items 

do not warn about CORRESPONDING with no matching items 
* ALWAYS active 

do not warn about dialect specific issues 

* ALWAYS active 


-Wgoto-different-section 


-Wno-error 
-Wno-error=<warning> 
-Wno-goto-section 


-Wno-ignored-error 


-Wno-missing-newline 
-Wno-others 
-Wno-pending 


-Wno-repository-checks 


-Wno-unfinished 


-Wno-unsupported 
-Wno-<warning> 
-Wparentheses 
-Wpossible-overlap 


-Wpossible-truncate 
-Wprototypes 


-Wredefinition 
-Wstrict-typing 


warn about GO TO a praragraph defined in a different section 
don’t treat warnings as errors 

don’t treat specified <warning> as error 

do not warn about GO TO section-name 

* ALWAYS active 

do not warn about errors in code parts which are 
unreachable and so normally ignored 

* ALWAYS active 

do not warn about missing newlines 

* ALWAYS active 

do not warn about different issues 

* ALWAYS active 

do not warn if pending features are used 

* ALWAYS active 


do not warn/check for program/function/external signature 
mismatch 

* ALWAYS active 

do not warn if unfinished features are used 

* ALWAYS active 

do not warn if runtime does not support a feature used 
disable warning enabled by default, -Wall or -Wextra 
warn if parentheses are omitted around AND within OR 
warn about MOVE of items that may overlap depending on 
variables 

* NOT set with -Wall 

warn about possible field truncation 

* NOT set with -Wall 

warn about missing FUNCTION prototypes/definitions 
warn about non-referenced ambiguous data items 

warn strictly about type mismatch 


-Wsuspicious-perform-thru 


-Wterminator 


-Wtruncate 
-Wunreachable 


warn if PERFORM THRU references procedures not in ascending 
order or multiple sections 

* ALWAYS active 

warn about lack of scope terminator END-XXX 

* NOT set with -Wall 

warn about field truncation from constant assignments 

warn about likely unreachable statements 

* NOT set with -Wall 
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Compiler options: 
-fsign=[ASCII|EBCDIC] define display sign representation 
* default: machine native 
-ffold-copy= [UPPER | LOWER] 
fold COPY subject to value 
* default: no transformation 
-ffold-cal1=[UPPER| LOWER] 
fold PROGRAM-ID, CALL, CANCEL subject to value 
* default: no transformation 
-fmax-errors=<number> maximum number of errors to report before 
compilation is aborted 
* default: 128 
-fintrinsics=[ALL|intrinsic 


function name(,name,...)] 

intrinsics to be used without FUNCTION keyword 
-fdump=<scope> dump data fields on abort, <scope> may be 

a combination of: ALL, WS, LS, RD, FD, SC, LO 
-fcallfh=<name> specifies <name> to be used for I/0 


as external provided EXTFH interface module 
-febcdic-table=[DEFAULT | RESTRICTED-GC | IBM| GCOS] 

define FBCDIC translation table: 

* default: translation to extended ASCII as per MF 

* restricted-gc: translation from restricted ASCII only 

* ibm: translation to restricted ASCII as per IBM 

* gcos: translation to extended ASCII as per GCOS7 
-fdefault-colseg=[ASCII |EBCDIC| NATIVE] 

define default collating sequence 

* default: NATIVE 
-fstack-extended store origin of entrypoints and PERFORM 

* turned on by -debug/-dump 
-fno-remove-unreachable 

disable remove of unreachable code 

* turned off by -g 


-ftrace generate trace code 

* scope: executed SECTION/PARAGRAPH 
-ftraceall generate trace code 

* scope: executed SECTION/PARAGRAPH/STATEMENTS 
-fsyntax-only syntax error checking only; don’t emit any output 
-fdebugging-line enable debugging lines 

* ?D’ in indicator column or floating >>D 
-fsource-location generate source location code 

* turned on by -debug/-ftraceall/-fec/-dump 
-fimplicit-init automatic initialization of the COBOL runtime system 


-fno-recursive-check disable check of recursive program call; 
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-fstack-check 


-fsection-exit-check 


effectively compiling as RECURSIVE program 

PERFORM stack checking 

* turned on by -debug/-g 

check that code execution does not leave the scope of 
SECTIONs 


-fimplicit-goback-check 


-fwrite-after 
-fmfcomment 
-facucomment 
-fno-trunc 
-fsingle-quote 
-foptional-file 


-fstatic-call 


check that code execution does not end implicit at end of 
PROCEDURE DIVISION 

use AFTER 1 for WRITE of LINE SEQUENTIAL 

* default: BEFORE 1 

?*? in column 1 treated as comment with listing suppression 
* FIXED/COBOL85/VARIABLE format only 

?>$? in indicator area treated as ’*’, 

>|? treated as floating comment 

allow numeric field overflow 

* non-ANSI behaviour 

use a single quote (apostrophe) for QUOTE 

* default: double quote 

treat all files as OPTIONAL 

* unless NOT OPTIONAL specified 

output static function calls for the CALL statement 


-fno-gen-c-decl-static-call 


-fgen-c-line-directives 


-fgen-c-labels 
-fno-theaders 
-fno-tsource 


-fno-tmessages 
-ftsymbols 


disable generation of C function declarations 
for subroutines with static CALL 


generate source location directives in C code; 

* turned on by -g 

generate extra labels in C sources; 

* turned on by -g 

suppress all headers and output of compilation 

options from listing while keeping page breaks 

suppress source from listing 

suppress warning and error summary from listing 
specify symbols in listing 


-fno-diagnostics-show-option 


suppress output of option that directly 
controls the diagnostic 


Compiler dialect configuration options: 
-freserved-words=<value> 


-ftab-width=1..12 
-ftext-column=72. .255 
-fpic-length=<number> 


use of complete/fixed reserved words 

number of spaces that are assumed for tabs 

right margin column number for fixed-form reference format 
maximum number of characters allowed in the PICTURE 
character-string 


Chapter 10 - Interfacing With The OS 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 631 


-fword-length=1..63 maximum word-length for COBOL (= programmer defined) words 
-fliteral-length=<number> 
maximum literal size in general 
-fnumeric-literal-length=1. .38 
maximum numeric literal size 
-fdefaultbyte=<value> default initialization for fields without VALUE, may be 
one of 
* character in quotes 
* decimal 0..255 representing a character 
* "init" to initialize to PICTURE/USAGE 
* "none" to do no explicit initialization 
* default: "init" 
-fformat=<value> default reference-format, may be one of: FIXED, FREE, 
COBOL85, VARIABLE, XOPEN, XCARD, CRT, TERMINAL, COBOLX 
-fbinary-size=<value> binary byte size - defines the allocated bytes according to 
PIC, may be one of: 2-4-8, 1-2-4-8, 1--8 
-fbinary-byteorder=<value> 
binary byte order, may be one of: native, big-endian 
-fassign-clause=<value> 
how to interpret ’ASSIGN word’: as ’ASSIGN EXTERNAL word’ or 
7ASSIGN DYNAMIC word’, may be one of: dynamic, external, 
ibm (= external), mf (= dynamic) 
-fscreen-section-rules=<value> 
which compiler’s rules to apply to SCREEN SECTION item 
clauses, may be one of: acu, gc, mf, rm, std, xopen 
-fdpc-in-data=<value> whether DECIMAL-POINT IS COMMA has effect in XML/JSON 
GENERATE, may be one of: none, xml, json, all 


-ffilename-mapping resolve file names at run time using environment variables 
-fpretty-display alternate formatting of numeric fields 

-fbinary-truncate numeric truncation according to ANSI 

-fcomplex-odo allow complex OCCURS DEPENDING ON 

-fodoslide adjust items following OCCURS DEPENDING (implies complex-odo) 


-findirect-redefines allow REDEFINES to other than last equal level number 
-frelax-syntax-checks allow certain syntax variations (e.g. REDEFINES position) 
-fref-mod-zero-length allow zero length reference-modification (only changed with 
EC-BOUND-REF-MOD active) 
-frelax-level-hierarchy 
allow non-matching level numbers 
-fselect-working require ASSIGN USING items to be in WORKING-STORAGE 
-flocal-implies-recursive 
LOCAL-STORAGE SECTION implies RECURSIVE attribute 


-fsticky-linkage LINKAGE SECTION items remain allocated between invocations 

-fmove-ibm MOVE operates as on IBM (left to right, byte by byte) 

-fperform-osvs exit point of any currently executing perform is recognized 
if reached 

-farithmetic-osvs limit precision in intermediate results to precision of final 
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-fconstant-folding 
-fhostsign 


result (less accurate) 

evaluate constant expressions at compile time 

allow hexadecimal value ’F’ for NUMERIC test of signed 
PACKED DECIMAL field 


-fprogram-name-redefinition 


-faccept-update 
-faccept-auto 


-fconsole-is-crt 
-fno-echo-means-secure 


-fline-col-zero-default 


program names don’t lead to a reserved identifier 
set WITH UPDATE clause as default for ACCEPT dest-item, 
instead of WITH NO UPDATE 
set WITH AUTO clause as default for ACCEPT dest-item, 
instead of WITH TAB 
assume CONSOLE IS CRT if not set otherwise 
NO-ECHO 
hides input with asterisks like SECURE 


assume a field DISPLAY starts at LINE 0 COL O (i.e. at the 
cursor), not LINE 1 COL 1 


-fdisplay-special-fig-consts 


-fbinary-comp-1 
-fnumeric-pointer 


-fmove-non-numeric-lit- 


special behaviour of DISPLAY SPACE/ALL X’01’/ALL X’02’/ALL 
X’?07’ 

COMP-1 is a 16-bit signed integer 

POINTER is a 64-bit unsigned integer 

to-numeric-is-zero 

imply zero in move of non-numeric literal to numeric items 


-fimplicit-assign-dynamic-var 


-fdevice-mnemonics 
-fxml-parse-xmlss 
-fareacheck 


implicitly define a variable if an ASSIGN DYNAMIC does not 
match any data item 
specifying device by mnemonic 
XML PARSE XMLSS 
check contents of Area A (when reference format supports 
Area A enforcement) , 
enabled checks include: 
* division, section, paragraph names, level indicators (FD, 
SD, RD, and CD), 
and toplevel numbers (01 and 77) must start in Area A; 
* statements must not start in Area A; and 
* separator periods must not be within Area A 


-fcomment-paragraphs=<support> 


comment paragraphs in IDENTIFICATION DIVISION (AUTHOR, 
DATE-WRITTEN, ...) 


-fcontrol-division=<support> 


-fpartial-replace-when- 


CONTROL DIVISION 

literal-src=<support> 

apply partial replacing with literal source operand even 
when it replaces with spaces only; 

* "skip" prevents such replacements 


-fmemory-size-clause=<support> 
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MEMORY-SIZE clause 
-fmultiple-file-tape-clause=<support> 

MULTIPLE-FILE-TAPE clause 
-flabel-records-clause=<support> 

LABEL-RECORDS clause 
-fvalue-of-clause=<support> 

VALUE-OF clause 
-fdata-records-clause=<support> 

DATA-RECORDS clause 
-ftop-level-occurs-clause=<support> 

OCCURS clause on top-level 
-fsame-as-clause=<support> 

SAME AS clause 
-ftype-to-clause=<support> 

TYPE TO clause 
-fusage-type=<support> USAGE type-name 
-fsynchronized-clause=<support> 

SYNCHRONIZED clause 
-fsync-left-right=<support> 

LEFT/RIGHT phrases in SYNCHRONIZED clause 
-fspecial-names-clause=<support> 

SPECIAL-NAMES clause 
-fgoto-statement-without-name=<support> 

GOTO statement without name 
-fstop-literal-statement=<support> 

STOP-literal statement 
-fstop-identifier-statement=<support> 

STOP-identifier statement 
-fstop-error-statement=<support> 

STOP ERROR statement 
-fdebugging-mode=<support> 

DEBUGGING MODE and debugging indicator 
-fuse-for-debugging=<support> 

USE FOR DEBUGGING 
-fpadding-character-clause=<support> 

PADDING CHARACTER clause 
-fnext-sentence-phrase=<support> 

NEXT SENTENCE phrase 
-flisting-statements=<support> 

listing-directive statements EJECT, SKIP1, SKIP2, SKIP3 
-ftitle-statement=<support> 

listing-directive statement TITLE 
-fentry-statement=<support> 

ENTRY statement 
-fmove-noninteger-to-alphanumeric=<support> 

move noninteger to alphanumeric 
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-fmove-figurative-constant-to-numeric=<support> 


move figurative constants to numeric 


-fmove-figurative-space-to-numeric=<support> 


move figurative constant SPACE to numeric 


-fmove-figurative-quote-to-numeric=<support> 


move figurative constant QUOTE to numeric 


-fodo-without-to=<support> 


OCCURS DEPENDING ON without to 


-fsection-segments=<support> 


section segments 


-falter-statement=<support> 


ALTER statement 


-fcall-overflow=<support> 


OVERFLOW clause for CALL 


-fnumeric-boolean=<support> 


boolean literals (B’1010’) 


-fhexadecimal-boolean=<support> 


hexadecimal-boolean literals (BX’A’) 


-fnational-literals=<support> 


national literals (N’UTF-16 string’) 


-fhexadecimal-national-literals=<support> 


hexadecimal-national literals (NX’265E’ ) 


-fnational-character-literals=<support> 


non-standard national literals (NC’UTF-16 string’) 


-fhp-octal-literals=<support> 


HP COBOL octal literals (%377) 


-facu-literals=<support> 


ACUCOBOL-GT literals (#B #0 #H #X) 


-fword-continuation=<support> 


continuation of COBOL words 


-fnot-exception-before-exception=<support> 


NOT ON EXCEPTION before ON EXCEPTION 


-faccept-display-extensions=<support> 


extensions to ACCEPT and DISPLAY 


-frenames-uncommon-levels=<support> 


RENAMES of O1-, 66- and 77-level items 


-flarger-redefines=<support> 


allow larger REDEFINES items 


-fsymbolic-constant=<support> 


constants defined in SPECIAL-NAMES 


-fconstant-78=<support> 


constant with level 78 item (note: has left to right 
precedence in expressions) 


-fconstant-01=<support> 


constant with level 01 CONSTANT AS/FROM item 


-fperform-varying-without-—by=<support> 
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PERFORM VARYING without BY phrase (implies BY 1) 
-freference-out-of-declaratives=<support> 

references to sections not in DECLARATIVES from within 

DECLARATIVES 
-fprogram-prototypes=<support> 

CALL/CANCEL with program-prototype-name 
-fcall-convention-mnemonic=<support> 

specifying call-convention by mnemonic 
-fcall-convention-linkage=<support> 

specifying call-convention by WITH ... LINKAGE 
-fnumeric-value-for-edited-item=<support> 

numeric literals in VALUE clause of numeric-edited items 
-fincorrect-conf-sec-order=<support> 

incorrect order of CONFIGURATION SECTION paragraphs 
-fdefine-constant-directive=<support> 

allow >> DEFINE CONSTANT var AS literal 
-ffree-redefines-position=<support> 

REDEFINES clause not following entry-name in definition 
-frecords-mismatch-record-clause=<support> 

record sizes does not match RECORD clause 
-frecord-delimiter=<support> 

RECORD DELIMITER clause 
-fsequential-delimiters=<support> 

BINARY-SEQUENTIAL and LINE-SEQUENTIAL phrases in 

RECORD DELIMITER 
-frecord-delim-with-fixed-recs=<support> 

RECORD DELIMITER clause on file with fixed-length records 
-fmissing-statement=<support> 

missing statement (e.g. empty IF / PERFORM) 
-fmissing-period=<support> 

missing period in PROCEDURE DIVISION (when reference format 

supports Area A enforcement) 
-fzero-length-literals=<support> 

zero-length literals, e.g. ’’ and "" 
-fxml-generate-extra-phrases=<support> 

XML GENERATE’s phrases other than COUNT IN 
-fcontinue-after=<support> 

AFTER phrase in CONTINUE statement 
-fgoto-entry=<support> ENTRY FOR GOTO and GOTO ENTRY statements 
-fassign-variable=<support> 

ASSIGN [TO] variable in SELECT 
-fassign-using-variable=<support> 

ASSIGN USING/VARYING variable in SELECT 
-fassign-ext-dyn=<support> 

ASSIGN EXTERNAL/DYNAMIC in SELECT 
-fassign-disk-from=<support> 
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ASSIGN DISK FROM variable in SELECT 
-fvsam-status=<support> 
VSAM status in FILE STATUS 
-fself-call-recursive=<support> 
CALL to own PROGRAM-ID implies RECURSIVE attribute 
-frecord-contains-depending-clause=<support> 
DEPENDING clause in RECORD CONTAINS 
-fpicture-l=<support> PICTURE string with ’L’ character 
where <support> is one of the following: 
?ok’, ’warning’, ’archaic’, ’obsolete’, ’skip’, ’ignore’, ’error’, 
>unconformable’ 


-fnot-reserved=<word> word to be taken out of the reserved words list 
-freserved=<word> word to be added to reserved words list 
-freserved=<word>:<alias> 

word to be added to reserved words list as alias 
-fnot-register=<word> special register to disable 
-fregister=<word> or <word>:<definition> 

special register to enable 


Each file specified on the cobc command constitutes a Compilation Unit. A compilation 
unit may be a single GnuCOBOL program — with or without nested subprograms(see 
[Independent vs Contained vs Nested Subprograms], page 675) — or multiple GnuCOBOL 
programs, separated by END PROGRAM or END FUNCTION marker lines, as appropriate. See 
[Independent vs Contained vs Nested Subprograms], page 675, for some examples of these 
marker lines. 


A compilation unit may also be a C-language source program, recognized as such by 
having a file extension of .c or an assembly-language program, recognized by its file exten- 
sion of .s. In such a case, COBOL compilation of that file will be bypassed by the cobc 
command; instead, the file will be passed directly to the C compiler or assembler (executed 
automatically by cobc). 


A compilation unit may also be an object-code module (output from the C compiler), 
recognized as such by having a file extension of .o. In these situations, all compilation will 
be bypassed, and the object code will be “bound” into the generated executable by the 
linker (an 1d command executed internally by the cobc command). 


Pre-compiled object-code subprograms may be automatically located by the GnuCOBOL 
compiler and the loader by using the LD_LIBRARY_PATH compilation-time environment vari- 
able (see [Compilation Time Environment Variables], page 641). If they are locatable 
through that environment variable, they need not be named on the cobc command. 


The collection of compilation units supplied on a single cobc execution constitute a 
Compilation Group. All executable code produced from a single compilation group will be 
collected together into a single executable file, whose filename will be the same as that of 
the first compilation unit specified on the cobc command. 
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The simplest mode of compilation is to generate a single executable file from one or more 

GnuCOBOL source files: 
cobc -x mainprog.cbl sub1.cbl sub2.cbl 

The main program must be the first program found in the first compilation unit 
(mainprog.cbl). The remainder of that compilation unit as well as the rest of the files in 
the compilation group (sub1.cbl and sub2.cbl) must be independent and/or contained 
subprograms (see [Independent vs Contained vs Nested Subprograms], page 675). 

This command assumes that all source files are in the directory from which the cobc 
command was executed. You are, of course, free to include full pathnames with any filename, 
if necessary. 

With the -x switch on the compiler command, a single directly-executable executable 
file (UNIX, Windows/Cygwin, OSX) or “exe” file (Windows, Windows/MinGW) will be 
generated. This executable file has the compiled code for all COBOL programs contained 
within the compilation group specified on the cobc command included in the file. 

Any subroutines or user-defined functions that weren’t included in any of the source files 
comprising the compilation group will be treated as dynamically loadable subprograms (see 
[Dynamic vs Static Subprograms], page 677). 

Optionally, the -o switch may be used in addition to -x to specify the name of the 
generated executable file. If -o switch is not specified, the filename of the 1st compilation 
unit will be used as the name of the executable file. The appropriate extension for the 
generated file (.exe, on a Windows computer, for example) will be added to the filename 
that is explicitly specified or implicitly assumed for the output file. 

Compilations may be performed to generate dynamically-loadable modules (or 
dynamically-loadable libraries, as they are frequently called). These compilations are 
performed by using the -m switch instead of -x switch: 

cobc -m mainprog.cbl sub1.cbl sub2.cbl 

When the -m switch is used, an operating-system-specific dynamically-loadable module 
is generated for each individual compilation unit, using the filename of each compilation unit 
as its module filename and either an extension of .so (UNIX, Windows/Cygwin), .dylib 
(OSX) or .d11 (Windows, Windows/MinGW). 

You may compile GnuCOBOL subprograms into assembler source code which can then 
be assembled and linked with a main program when that main program is compiled. To 
create such an assembler source file, compile the subprogram(s) as follows: 

cobc -S sprogi.cbl 

The above generates an assembler source file named sprogi1.s. If you have multiple 
subprograms to compile this way, just string their file names out on the command. Each 
will be translated to its own assembler source file. 


Later, when you wish to compile a calling program and combine any needed assembly 
language subroutines in (as static subroutines — see [Dynamic vs Static Subprograms], 
page 677), use a command such as this: 

cobc -x mainprog.cbl sprogi.s 


10.1.1.1. cobc option -Xref an example 


The following shows the output from using -Xref. 
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Using the internal -Xref as extra options -X -t prog.list 


GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 


LINE BG AEN Aiscettts Bic tt tie teed ag yagie beat aati Gregan ir Bede cada o Sahaaaet el atana a eG caeeg 


000001 000001 IDENTIFICATION DIVISION. 
000002 000002 PROGRAM-ID. prog. 
000003 000003 ENVIRONMENT DIVISION. 
000004 000004 CONFIGURATION SECTION. 
000005 000005 DATA DIVISION. 
000006 000006 WORKING-STORAGE SECTION. 
000007 000007 COPY ’values.cpy’. 

000001C 000001 78 I VALUE 20. 

000002C 000002 78 J VALUE 5000. 
000003C 000003 78 M _ VALUE 5. 

000008 000008 01 SETUP-REC. 


000009 000009 05 FL1 PIC X(04). 

000010 000010 05 FL2 PIC ZZZZZ. 

000011 000011 05 FL3 PIC 9(04). 

000012 000012 05 FL4 PIC 9(08) COMP. 

000013 000013 05 FLS PIC 9(04) COMP-4. 

000014 000014 05 FL6 PIC Z,2Z2Z.99. 

000015 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE. 
000016 000016 05 FL8& PIC X(04). 

000017 000017 05 FL9 REDEFINES FL8 PIC 9(04). 

000018 000018 O05 FLA. 

000019 000019 10 FLB OCCURS I TIMES. 

000020 000020 15 FLC PIC X(02). 

000021 000021 10 FLD PIC X(20). 

000022 000022 05 FLD1 PIC X(100). 

000023 000025 05 FLD3 PIC X(3). 

000024 000026 05 FLD4 PIC X(4). 

000025 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FLO. 
000026 000024 10 FILLER PIC X(01). 

000027 000027 PROCEDURE DIVISION. 

000028 000028 STOP RUN. 

GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 
NAME DEFINED REFERENCES 
SETUP-REC 8 referenced by child 

FL1 9 not referenced 

FL2 10 not referenced 


Page 0001 


Page 0002 
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FL3 11 not referenced 

FL4 12 not referenced 

FL5 13 25 x1 
FL6 14 not referenced 

FL7 15 not referenced 

FL8 16 not referenced 

FL9 17 not referenced 

FLA 18 not referenced 

FLB 19 not referenced 

FLC 20 not referenced 

FLD 21 not referenced 

FLD1 22 not referenced 

FLD3 23 not referenced 

FLD4 24 not referenced 

FLD2 25 not referenced 

GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 Page 0003 
LABEL DEFINED REFERENCES 

E prog 27 


O warnings in compilation group 
0 errors in compilation group 


10.1.1.2. Cross Reference listing using cobxref 


This program is found in the contrib area or by itself in Sourceforge under its own name 
(cobxref). 


The following shows the output from using cobxref with the same program example. 


Note that cobxref also reports the COPY depth which can be up to 9 and includes the 
program being compiled as depth 1. 


Using cobxref with command cobxref prog.cbl : 


ACS Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 
Page 1 


000001 IDENTIFICATION DIVISION. 
000002 PROGRAM-ID. prog. 
000003 ENVIRONMENT DIVISION. 
000004 CONFIGURATION SECTION. 
000005 DATA DIVISION. 
000006 WORKING-STORAGE SECTION. 
000007*COPY ’values.cpy’. 

000001 78 I VALUE 20. 


ONOoOFRWNE 
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9 000002 78 J VALUE 5000. 
10 000003 78 M_ VALUE 5. 
11 000008 01 SETUP-REC. 


12 000009 05 FL1 PIC X(04). 

13 000010 05 FL2 PIC ZZZZZ. 

14 000011 05 FL3 PIC 9(04). 

15 000012 05 FL4 PIC 9(08) COMP. 

16 000013 05 FL5 PIC 9(04) COMP-4. 

17 000014 05 FL6 PIC Z,2Z2Z.99. 

18 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE. 

19 000016 05 FL8 PIC X(04). 

20 000017 05 FL9 REDEFINES FL8 PIC 9(04). 

21 000018 O05 FLA. 

22 000019 10 FLB OCCURS I TIMES. 

23 000020 15 FLC PIC X(02). 

24 000021 10 FLD PIC X(20). 

25 000022 05 FLD1 PIC X(100). 

26 000025 05 FLD3 PIC X(3). 

27 000026 05 FLD4 PIC X(4). 

28 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FLO. 

29 000024 10 FILLER PIC X(01). 

30 000027 PROCEDURE DIVISION. 

31 000028 STOP RUN. 

32 *>>>Info: Total Copy Depth Used = 02 

ACS Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 

Page 2 


Symbols of Module: PROG (PROG) 


Data Section (WORKING-STORAGE) Defn Locations 
RCE Serer ee Seer ane ue eeenee yearn eynnmne try ener) EP ONS ay Wer OE NY OL ANTE aN Ee Te ALERT AEST Pare meee: PET nee PE ES Te ty 
FL1 000012W 

FL2 000013W 

FL3 000014W 

FL4 000015W 

FLS 000016W 000028 
FL6 000017W 

FL7 000018W 

FL8 000019W 000020 
FL9 000020W 

FLA 000021W 

FLB 000022W 

FLC 000023W 
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FLD 000024W 

FLD1 000025W 

FLD2 000028W 

FLD3 000026W 

FLD4 000027W 

I 000008W 000022 
J O000009W 000028 
M 000010W 000028 
SETUP-REC 000011W 

ACS Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 

Page 3 


Symbols of Module: PROG (PROG) 


None 


10.1.2. Compilation Time Environment Variables 


The following are the various environment variables that can play a role in the compilation 
of GnuCOBOL programs. 


COB_CC * Set to the name of the C compiler you wish GnuCOBOL to use. 


Use this feature at your own risk — you should always use the c compiler your 
gnucobol build was generated for. 


COB_CFLAGS * 
Set to any switches that you’d like to pass on to the C compiler from the cobc 
compiler (in addition to any that cobc will specify). 


COB_CONFIG_DIR * 
Set to the path to the folder where GnuCOBOL config files are kept. 


COB_COPY_DIR * 
If copybooks your program needs are not stored in the same directory as your 
program, set this environment variable to the folder in which the copybooks 
may be found (IBM mainframe programmers will recognize this as SYSLIB). 


COB_LDADD 
Set to any additional linker switches (1d) that can specify where standard li- 
braries that must be linked with the program can be found. The default is "" 


(empty). 


COB_LDFLAGS 
Set to any linker (1d) switches that you’d like to pass on to the C compiler from 
the cobc compiler (in addition to any that cobc will specify). 
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COB_LIBS * 
Set to any linker switches (1d) that specify where standard libraries that must 
be linked with the program can be found. 


COBCPY This environment variable provides an additional means of specifying where 
copybooks may be found by the compiler (see also COB_COPY_DIR, above). 


LD_LIBRARY_PATH 
If you are planning on using static-linked subroutine libraries, set this variable 
to the path of the directory containing your libraries. 


TMPDIR 

TMP Set to a directory/folder appropriate to create temporary files in. The inter- 
mediate working files created by the compiler will be created here (and deleted 
once they’re no longer needed). 


The variable TMPDIR is checked for a valid path first; if that isn’t set, then TMP 
is checked. 


On a Windows system, the TMP environment variable is normally set for you 
when you logon. If you wish to use a different temporary folder, you may set 
TMPDIR yourself and have no fear of disrupting other Windows software that 
relies on TMP. 
( >) 
* The starred environment variables above have default values, established when the ver- 
sion of GnuCOBOL you are using was built. To see these default values, as well as other 
build-specific information, execute the command: 


cobc -i 


10.1.3. Predefined Compilation Variables 


GnuCOBOL defines compilation variables when certain conditions are true. 


If the condition associated with a variable is false, the variable is not defined during 
compilations. 


DEBUG The -d debug flag is specified. 


EXECUTABLE 
The module being compiled contains the main program. 


GCCOMP The size of a COMP item is determined according to the GnuCOBOL scheme, 
where for a PICTURE of length: 


1-2 item has 1 byte 

3-4 item has 2 bytes 
5-9 item has 4 bytes 
10-18 item has 8 bytes. 
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GNUCOBOL GnuCOBOL is compiling the source unit. 


HOSTSIGNS 
A signed packed-decimal item’s value may be considered NUMERIC if the sign 
has value X"F". 


IBMCOMP ‘The size of a COMP item is determined according to the IBM scheme, where for 
a PICTURE of length: 


1-4 item has 2 bytes 

5-9 item has 4 bytes 

10-18 item has 8 bytes. 
MODULE The module being compiled does not contain the main program. 
NOHOSTSIGNS 


A signed packed-decimal item’s value may not be considered 
NUMERIC if the sign has value X"F". 


NOIBMCOMP 
The size of a COMP item is not determined according to the IBM scheme. 


NOSTICKYLINKAGE 
Sticky-linkage (linkage-section items remaining allocated between invocations) 
is not enabled. 


NOTRUNC Numeric data items are truncated according to their internal representation. 
P64 Pointers are greater than 32 bits long 


STICKY-LINKAGE 
Sticky-linkage (linkage-section items remaining allocated between invocations) 
is enabled. 


TRUNC Numeric data items are truncated according to their PICTURE clauses. 
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10.1.4. Locating Copybooks 


The GnuCOBOL compiler will attempt to locate copybooks by searching for them in the 
following folders. The search will occur in the sequence shown below, and will terminate 
once a copybook is found. 
1. The folder named as the library-name-1 on the COPY statement (see [COPY], page 63). 
2. The folder in which the program being compiled resides. 
3. The folder named on the -I switch. 
4. Each of the folders named on the COBCPY compilation-time environment variable (see 
[Compilation Time Environment Variables], page 641). 
A single folder may be named or multiple folders may be specified, separated by a 
system-appropriate delimiter character. When multiple folders are specified, they will 
be searched in the order they are named on the environment variable. 
If the GnuCOBOL compiler you are using was built to utilize a native Windows envi- 
ronment, use a semicolon (‘;’) as the delimiter character. 
If, however, the GnuCOBOL compiler was built for a Unix, OSX or Linux environment, 
or was built for a Windows environment utilizing either the Cygwin or MinGW Unix 
emulators, use a colon character (‘:’) as the delimiter. 
5. The single folder specified on the COB_COPY_DIR environment variable. 


As each of the above folders is searched for a copybook — COPY XXXXXXXX., for example 

— the GnuCOBOL compiler will attempt to locate the copybook file by any of the following 
names, in the sequence shown: 

XXXXXXXX.CPY 

XXXXXXXX.CBL 

XXXXXXXX.COB 

XXXXXXXX. cpy 

XXXXXXXX.cb1 

XXXXXXXX.cob 

XXXXXXXX 


The COPY statement is case-sensitive on UNIX systems; COPY copybookname and COPY 
COPYBOOKNAME will both fail to locate the CopyBookName copybook on a UNIX system. 


Windows implementations of GnuCOBOL may, or may not, be similarly case sensitive 
with regard to copybook names, depending upon the Windows version and GnuCOBOL 
build options — it is safest to simply treat the COPY command as case-sensitive in all 
environments. 


It is possible, however, to automatically cause all COPY statements to “fold” the names of 
all copybooks to upper-case by specifying the -ffold-copy switch with the upper option 
(i.e. --fold-copy=upper) to the GnuCOBOL compiler. Similarly, names could be folded 
to lower-case by using the lower option (i.e. --fold-copy=lower. If copybook libraries 
are maintained entirely using upper- or lower-case file names and extensions, either of these 
options will allow copybooks to be found regardless of how the programmer entered their 
names on COPY statements. 
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Case-folding may also be turned on and off within the program source code using the 
CDF >>SET statement (see [>>SET], page 71). 


10.1.5. Compiler Configuration Files 


GnuCOBOL uses compiler configuration files to define various options that will control 
the compilation process. These configuration files are specified using the -conf switch 
compilation switch and are found in the folder defined by the COB_CONFIG_DIR compilation- 
time environment variable (see [Compilation Time Environment Variables], page 641). 

If this is not defined under *nix it will default to /usr/local/share/gnucobol/config. 

The following is a verbatim listing of the default configuration file (the one used if you 
don’t specify the -conf switch), just to show you the types of settings that may appear and 
taken from v3.1.2 : 


GnuCOBOL compiler configuration 


Copyright (C) 2001-2012, 2014-2020 Free Software Foundation, Inc. 
Written by Keisuke Nishida, Roger While, Simon Sobisch, Edward Hart, 
Ron Norman 


This file is part of GnuCOBOL. 


The GnuCOBOL compiler is free software: you can redistribute it 
and/or modify it under the terms of the GNU General Public License 

as published by the Free Software Foundation, either version 3 of the 
License, or (at your option) any later version. 


GnuCOBOL is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
GNU General Public License for more details. 


You should have received a copy of the GNU General Public License 
along with GnuCOBOL. If not, see <https://www.gnu.org/licenses/>. 


# HH HH HH HHH HH HH OH OH HH OH OF OF 


# Value: any string 
name: "GnuCOBOL" 


# Value: enum 

standard-define 0) 
CB_STD_GC = 0, 
CB_STD_MF, 

CB_STD_IBM, 

CB_STD_MVS, 
CB_STD_BS2000, 
CB_STD_ACU, 


# HH H H HF 
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# CB_STD_85, 
# CB_STD_2002, 
# CB_STD_2014 


# Value: int 

tab-width: 8 

text-column: 72 

# Maximum word-length for COBOL words / Programmer defined words 
# Be aware that GC checks the word length against COB_MAX_WORDLEN 
# first (currently 63) 

word-length: 63 


# Maximum literal size in general 
literal-length: 8191 


# Maximum numeric literal size (absolute maximum: 38) 
numeric-literal-length: 38 


# Maximum number of characters allowed in the character-string (max. 255) 
pic-length: 255 


# Default assign type 
# Value: ’dynamic’, ’external’ 
assign-clause: dynamic 


# If yes, file names are resolved at run time using 

# environment variables. 

# For example, given ASSIGN TO "DATAFILE", the file name will be 
# 1. the value of environment variable ’DD_DATAFILE’ or 

# 2. the value of environment variable ’dd_DATAFILE’ or 

# 3. the value of environment variable ’DATAFILE’ or 

# 4. the literal "DATAFILE" 

# If no, the value of the assign clause is the file name. 

# 


filename-mapping: yes 


# Alternate formatting of numeric fields 
pretty-display: yes 


# Allow complex OCCURS DEPENDING ON 
complex-odo: no 


# Allow REDEFINES to other than last equal level number 
indirect-redefines: no 


# Binary byte size - defines the allocated bytes according to PIC 
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# Value: Signed unsigned bytes 
# SSS ° SSS SSS! eS 
# ?2-4-8°? 1- 4 same 2 
# - 9 same 4 
# 10 - 18 same 8 
# 

# ?1-2-4-8? dh 2 same 1 
# 3 - 4 same 2 
# 5 - 9 same 4 
# 10 - 18 same 8 
# 

# ?1--8? 1. 2 LS; 12 1 
# 3 - 4 3 - 4 2 
# 5 - 6 pus of 3 
# ee 8- 9 4 
# 10 - 11 10 - 12 5 
# 12 - 14 13 - 14 6 
# 15 - 16 15 - 16 7 
# 17 - 18 17 - 18 8 
# 

binary-size: 1-2-4-8 


# Numeric truncation according to ANSI 
binary-truncate: yes 


# Binary byte order 
# Value: ’native’, ’big-endian’ 
binary-byteorder: big-endian 


# Allow larger REDEFINES items 
larger-redefines-ok: no 


# Allow certain syntax variations (eg. REDEFINES position) 
relax-syntax-checks: no 


# Allow zero length reference-modification 
# (only checked with active EC-BOUND-REF-MOD) 
ref-mod-zero-length: yes 


# Perform type OSVS - If yes, the exit point of any currently 
# executing perform is recognized if reached. 


perform-osvs : no 


# Compute intermediate decimal results like IBM OSVS 
arithmetic-osvs: no 
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# MOVE like IBM (mvc); left to right, byte by byte 
move-ibm: no 


# SELECT RELATIVE KEY and ASSIGN fields must be in WORKING-STORAGE 
select-working: no 


# LOCAL-STORAGE SECTION implies RECURSIVE attribute 
local-implies-recursive: no 


# If yes, LINKAGE SECTION items remain allocated 
# between invocations. 
sticky-linkage: no 


# If yes, allow non-matching level numbers 
relax-level-hierarchy: no 


# If yes, evaluate constant expressions at compile time 
constant-folding: yes 


# Allow Hex ’F’ for NUMERIC test of signed PACKED DECIMAL field 
hostsign: no 


# If yes, set WITH UPDATE clause as default for ACCEPT dest-item, 
# except if WITH NO UPDATE clause is used 
accept-update: no 


# If yes, set WITH AUTO clause as default for ACCEPT dest-item, 
# except if WITH TAB clause is used 
accept-auto: no 


# If yes, DISPLAYs and ACCEPTs are, by default, done on the CRT (i.e., using 
# curses). 
console-is-crt: no 


# If yes, allow redefinition of the current program’s name. This prevents its 
# use in a prototype-format CALL/CANCEL statement. 
program-name-redefinition: yes 


# If yes, NO ECHO/NO-ECHO/OFF is the same as SECURE (hiding input with 
# asterisks, not spaces). 
no-echo-means-secure: no 


# If yes, the first item in a field screen ACCEPT/DISPLAY (e.g. DISPLAY x UPON 
# CRT) is located after the previous ACCEPT/DISPLAY (as though LINE 0 COL O had 
# been specified). 

line-col-zero-default: yes 
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# If yes, DISPLAY SPACES acts as ERASE EOS, DISPLAY X"01" acts as ERASE EOL, 
# DISPLAY X"02" acts as BLANK SCREEEN and DISPLAY X"07" acts as BELL. Note 
# DISPLAY LOW-VALUE is excluded from this; it will always just position the 


# cursor. 
display-special-fig-consts: no 


# If yes, COMP-1 is a signed 16-bit integer and any PICTURE clause is ignored. 


binary-comp-1: no 


# If yes, POINTER is handled as BINARY-DOUBLE UNSIGNED instead of its own class 


numeric-pointer: no 


# auto-adjust to zero like MicroFocus does 


move-non-numeric-lit-to-numeric-—is-zero: 


no 


# If yes, implicitly define a variable for an ASSIGN DYNAMIC which does not 


# match an existing data item. 
implicit-assign-dynamic-var: yes 


# What rules to apply to SCREEN SECTION items clauses 


screen-section-rules: gc 


# Whether DECIMAL-POINT IS COMMA has effect in XML/JSON GENERATE 


dpc-in-data: xml 


# Dialect features 
# Value: ’ok’, ’warning’, ’archaic’, 
# >unconformable’ 


alter-statement: 
comment—paragraphs: 
call-overflow: 
data-records-clause: 
debugging-mode: 
use-for-debugging: 
listing-statements: 
title-statement: 

entry-statement: 
goto-statement-without-name: 
label-records-clause: 
memory-size-clause: 
move-noninteger-to-alphanumeric: 
move-figurative-constant-to-numeric: 
move-figurative-space-to-numeric: 
move-figurative-quote-to-numeric: 
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obsolete’, ’skip’, ’ignore’, ’error’, 


obsolete 

obsolete 

archaic 

obsolete 

ok 

ok 

skip # may be a user-defined word 
skip # may be a user-defined word 
ok 

obsolete 

obsolete 

obsolete 

error 

archaic 

error 

obsolete 
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multiple-file-tape-clause: obsolete 
next-sentence-phrase: archaic 
odo-without-to: warning 
padding-character-clause: obsolete 
section-segments: ignore 
stop-literal-statement: obsolete 
stop-identifier-statement: obsolete 
same-as-—clause: ok 
type-to-clause: ok 
usage-type: ok 
synchronized-clause: ok 
special-names-clause: ok 
top-level-occurs-clause: ok 
value-of-clause: obsolete 
numeric-—boolean: ok 
hexadecimal-boolean: ok 
national-literals: ok 
hexadecimal-national-literals: ok 
national-character-literals: warning 
# TO-DO: Add separate config option for H"..." to be unsupported,numeric,non-numeric (acu) 
acu-literals: unconformable 
hp-octal-literals: unconformable 
word-continuation: warning 
not-exception-before-exception: ok 
accept-display-extensions: ok 
renames-uncommon-levels: ok 
symbolic-constant: ok 
constant-78: ok 
constant-0O1: ok 
perform-varying-without-by: ok 
reference-out-of-declaratives: warning 
program-prototypes: ok 
call-convention-mnemonic: ok 
call-convention-linkage: ok 
numeric-value-for-edited-item: ok 
incorrect-conf-sec-order: ok 
define-constant-directive: archaic 
free-redefines-position: warning 
records-mismatch-record-clause warning 
record-delimiter: ok 
sequential-delimiters: ok 
record-delim-with-fixed-recs: ok 
missing-statement: warning 
zero-length-literals: ok 
xml-generate-extra-phrases: ok 
continue-after: ok 
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goto-entry: warning 
assign-variable: ok 
assign-using-variable: ok 
assign-ext-dyn: ok 
assign-disk-from: ok 
vsam-status: ignore 


# use complete word list; synonyms and exceptions are specified below 


reserved-words: 


# not-reserved: 


# Value: Word to be taken out of the reserved words list 


not-reserved: 
# reserved: 


default 


TERMINAL 


651 


# Entries of the form word-1=word-2 define word-1 as an alias for default 


# reserved word word-2. No spaces are allowed around the equal sign. 


reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 
reserved: 


15 January 2023 


AUTO-SKIP=AUTO 
AUTOTERMINATE=AUTO 
BACKGROUND-COLOUR=BACKGROUND-COLOR 
BEEP=BELL 
BINARY-INT=BINARY-LONG 
BINARY-LONG-LONG=BINARY-DOUBLE 
CELLS=CELL 

COLOURS=COLORS 
EMPTY-CHECK=REQUIRED 
EQUALS=EQUAL 
FOREGROUND-COLOUR=FOREGROUND-COLOR 
HIGH-VALUES=HIGH-VALUE 
INITIALISE=INITIALIZE 
INITIALISED=INITIALIZED 
LENGTH-CHECK=FULL 
LOW-VALUES=LOW-VALUE 
ORGANISATION=ORGANIZATION 
PIXELS=PIXEL 
SYNCHRONISED=SYNCHRONIZED 
TIMEOUT=TIME-OUT 

VALUES=VALUE 

ZEROES=ZERO 

ZEROS=ZERO 
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10.2. Running Programs 


Once GnuCOBOL programs have been compiled into either directly-executable programs 
(created via the -x switch) or dynamically-loadable libraries (created via the -m switch), 
those programs may be executed from any shell environment. The exact manner in which 
the two are executed will differ, as described in the upcoming sections. 


10.2.1. Direct Execution 


GnuCOBOL programs compiled with the -x switch will be generated as directly-executable 
programs. For example, a native Windows or Windows/MinGW build of GnuCOBOL will 
generate an .exe file when the -x switch switch is specified to the compiler. 


On Unix, OSX, or Windows/Cygwin builds, the -x switch switch will generate an exe- 
cutable binary file, usually with no particular extension unless one is explicitly requested 
of the compiler via the -o switch. 


On a UNIX system this means the programs may be executed from a command shell such 
as bash, csh, ksh and so forth. When a GnuCOBOL program runs on a Windows system, it 
runs within a console window (i.e. cmd.exe). OSX versions of GnuCOBOL programs run 
within a terminal.app window. 


Interactions between the program and the user will take place using the standard input, 
standard output and standard error streams. Any screen section I/O performed by the 
program will take place within the terminal window. 


Direct program execution syntax is [path] program [arguments]. 
For example: 
/usr/local/printaccount ACCT=6625378 
or 
cC:\\Users\\Me\\Documents\\Programs\\printaccount.exe ACCT=6625378 


10.2.2. Executing Dynamically-Loadable Libraries 


As discussed previously, dynamically-loadable libraries are created via the compiler’s -m 
switch. Once so created, the program(s) in these libraries are executed from the command 
line (via the GnuCOBOL cobcrun utility), or as dynamically-loadable subprograms. 


10.2.2.1. cobcrun - Command-line Execution 


It is possible to generate executable modules for all GnuCOBOL programs, not just sub- 
programs, by choosing to use the -m switch option to specify the loader output format, 
even for main programs. 


Some may prefer to compile their GnuCOBOL main programs into these dynamically- 
loadable modules in the interests of using the same general compilation command for all 
programs without having to think “Is it a main program or a subprogram?”. 


Main programs compiled in this manner should be executed as follows: 
[path] cobcrun program [arguments] 


Do not specify the .so or .d1l extension on the program name. The program value 
must exactly match the primary entry-point name of the main program (including upper- 
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and lower-case letters), unless you are planning on using Call Folding (see [Dynamically 
Loaded Subprograms], page 653). 

The general usage and syntax of cobcrun is as follows as issued by running cobcrun -h 
(or —help) : 
GnuCOBOL module loader 


Usage: cobcrun [options] PROGRAM [parameter ...] 
or: cobcrun options 


Options: 
-h, -help display this help and exit 
-V, -version display cobcrun and runtime version and exit 
-i, -info display runtime information (build/environment) 
-v, -verbose display extended output with --info 
-c <file>, -config=<file> set runtime configuration from <file> 
-r, -runtime-config display current runtime configuration 


(value and origin for all settings) 

-M <module>, -module=<module> set entry point module name and/or load path 
where -M module prepends any directory to the 
dynamic link loader library search path 
and any basename to the module preload list 
(COB_LIBRARY_PATH and/or COB_PRELOAD) 


Here are two examples of using cobcrun. First, on a Unix, OSX or Windows/Cygwin 
system: 

cd /usr/local 

cobcrun printaccount acct=6625378 


Or, on a Native Windows or Windows/MinGW system: 


cd C:\Users\Me\Documents\Programs 
cobcrun printaccount.exe acct=6625378 


Note how the cobcrun command does not allow a path to be specified with the program 
name — the directory in which the programs dynamically loadable module exists must 
either be the current directory or must be defined in the current PATH. 


10.2.2.2. Dynamically Loaded Subprograms 


Dynamically-loaded subprograms are executed (from a COBOL syntax point of view) just 
like any other subprograms. What makes them unique, however, is that they are loaded into 
memory only when they are actually used the first time during the execution of a program. 


When a dynamically-loadable module needs to be loaded (because it is not already in 
memory from a previous subprogram execution), the dynamically-loadable library will be 
sought by libcob in each directory named in the library specified by the COB_LIBRARY_ 
PATH run-time environment variable will be searched and if not found then. Finally, if it 
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still cannot be located, execution will be terminated with an error message (libcob: Cannot 
find module ’rrxxxrrx’). For speed performance purposes all such should therefore be stored 
within the directories pointed to by the environment variable COB_LIBRARY_PATH run-time 
environment variable. 


The process of locating dynamically-loadable modules is case sensitive on UNIX systems; 
CALL "dynsub" and CALL "DYNSUB" will both fail to locate the DynSub.so library on a UNIX 
system. 


Windows implementations of GnuCOBOL may, or may not, be similarly case sensitive 
with regard to library names, depending upon the Windows version and GnuCOBOL build 
options — it is safest to simply treat library names as case sensitive in all environments. 


It is possible, however, to automatically cause all library names to ’fold’ to upper-case 
by specifying the -ffold-call switch with the “upper” option (i.e. --fold-call=upper) 
to the GnuCOBOL compiler. Similarly, library names could be folded to lower-case by 
using the “lower” option (i.e. --fold-call=lower. If libraries are maintained entirely 
using upper- or lower-case file names, either of these options will allow libraries to be found 
regardless of how the programmer entered their names on CALL statements. 


See [Sub-Programming], page 675, for a complete discussion of sub-programming. 


10.2.3. Run Time Environment Variables 


The following is a list of the various environment variables that can play a role in the 
execution of GnuCOBOL programs. 


COB_DISPLAY_WARNINGS 
If set to a value of ‘Y’, any run-time warnings (such as noting the implicit 
closing of open files when a GOBACK statement (see [GOBACK], page 334) or 
STOP statement (see [STOP], page 399) with the RUN option is executed) will be 
displayed. Any other value for this environment variable (including not setting 
the variable at all) will suppress such messages. 


COB_LIBRARY_PATH 
At runtime, GnuCOBOL will attempt to locate and load any application dy- 
namically loadable libraries used this variable that points to the directories 
specified, if it wasn’t found there, using the PATH environment variable. 


COB_LOAD_CASE 
If set to either UPPER or LOWER, this environment variable will internally convert 
referenced entry point names to either upper- or lower-case before initiating 
searches for dynamically loadable modules. The UPPER and LOWER values of the 
environment variable are actually case insensitive. 


COB_PHYSICAL_CANCEL 
If set to ‘Y’, ‘y’ or ‘1’, a CANCEL statement (see [CANCEL], page 298) will 
physically unload a subprogram dynamically loadable module. If set to anything 
else, a CANCEL statement (see [CANCEL], page 298) logically unloads a module 
so that subsequent use will re-initialize the module as if it had actually been 
reloaded, but the overhead of actually reloading the module will be avoided. 
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COB_PRE_LOAD 
If set to any non-null value, this variable will cause all dynamically loadable 
libraries to be loaded when the program begins execution (rather than searching 
for and loading the module upon first use). 


COB_SET_DEBUG 
If a USE FOR DEBUGGING (see [DECLARATIVES], page 254) section exists, the 
code within it will be disabled unless this environment variable is set to a value 
of ‘Y’, ‘y’ or ‘1’. 


COB_SET_TRACE 
If the -ftrace switch (trace procedures) or -ftraceall switch (trace pro- 
cedures and statements) was used when the program was compiled, setting this 
environment variable to a value of ‘Y’ will activate the trace at the point the 
program begins execution. Setting this environment variable to any other value 
(or never setting it to ANY value) will disable tracing. Tracing, if configured 
by one of the two switches described above, can also be controlled via the the 
READY TRACE statement (see [READY TRACE], page 370) and RESET TRACE 
statement (see [RESET TRACE], page 372). If COB_SET_TRACE is set to Y, 
then tracing will always occur regardless of the presence of READY TRACE 
or RESET TRACE so in effect they will have no action on program execution. 


COB_SCREEN_ESC 
If set to any non-blank value, this variable allows a ACCEPT data-item state- 
ment (see [ACCEPT data-item], page 272) to detect the Esc key. 


COB_SCREEN_EXCEPTIONS 
Setting this variable to any non-blank value will allow the ACCEPT data-item 
statement (see [ACCEPT data-item], page 272) to detect the pressing of the 
Esc, PgUp and PgDn keys. 


COB_SORT_MEMORY 
The value of this variable (an integer) will be used to define how much memory 
will be allocated for use in sorting. If the value is 1048576 or greater, that value 
will be used “as is” as the amount of memory (in bytes) to allocate. If the value 
is less than 1048576, the value will specify how many MB of memory will be 
allocated. The default sort memory amount is 128 MB. 


COB_SWITCH_n 
(n=0 to 15); These environment variables correspond to SWITCH-O through 
SWITCH-15, defined in the SPECIAL-NAMES (see [SPECIAL-NAMES], page 92) 
paragraph. Setting them to ON will activate them; any other value turns them 
off. 


COB_SYNC If set to a value of upper- or lower-case ‘p’, this variable will force a file commit 
every time a file is written to (ensuring that data is immediately written to the 
file rather than retained in memory until a future commit occurs). This will 
slow-down update access to files, but will provide for better integrity in the 
event of a program failure. 
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COB_TRACE_FILE 
If set to any non-null value, this environment variable specifies the file to which 
all -ftrace switch and -ftraceall switch output will be written. If this is 
NOT set to a value, all -ftrace switch and -ftraceall switch output will 
be written to STDERR, where it may be piped via a "2> filename" on the 
command that executes the program. 


DB_HOME If your GnuCOBOL build uses the Berkeley Database (BDB) package, use 
this environment variable to specify the folder in which the lock management 
files to be associated with all non-SORT files opened by the program will be 
stored. ORGANIZATION INDEXED (see [ORGANIZATION INDEXED], page 115) 
files will also have their data file allocated in the folder pointed to by this 
environment variable, if it exists.. Having this variable defined will activate 
record locking features on the READ statement (see [READ], page 366), REWRITE 
statement (see [REWRITE], page 374) and WRITE statement (see [WRITE], 
page 417). Even with DB_HOME, locking will not work with ORGANIZATION 
SEQUENTIAL (see [ORGANIZATION SEQUENTIAL], page 109), ORGANIZATION 
LINE SEQUENTIAL (see [ORGANIZATION LINE SEQUENTIAL], page 111) or 
ORGANIZATION RELATIVE files with GnuCOBOL builds created for Win- 
dows/MinGW. ORGANIZATION INDEXED locks will work with Windows/MinGW 
+ BDB and all locks will work for all file organizations with UNIX GnuCOBOL 


builds. 
PATH The GnuCOBOL "bin" directory should be defined in the PATH. 
TMPDIR 
TMP 
TEMP One of these environment variables must be set to a directory /folder appropriate 


to create temporary files in. They will be checked in the order shown. This will 
be used by the SORT statement (see [SORT], page 391) and MERGE statement 
(see [MERGE], page 349) to create temporary work files. You may also use this 
folder for any temporary files your application may require. 


Also used during execution of programs is runtime.cfg also found in 
/usr/local/share/gnucobol/config for *nix and this file can also be changed 
to match your environment if needed. When viewing, note the Default settings. 


10.2.3.1. General instructions 


The initial runtime.cfg file is found in the $COB_CONFIG_DIR/config 

( COB_CONFIG_DIR defaults to installdir/gnucobol ). 

The environment variable COB_RUNTIME_CONFIG may define a different runtime 
configuration file to read. 


If settings are included in the runtime environment file multiple times 
then the last setting value is used, no warning occurs. 


Settings via environment variables always take precedence over settings 
that are given in runtime configuration files. And the environment is 
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checked after completing processing of the runtime configuration file(s) 


All values set to string variables or environment variables are checked 
for ${envvar} and replacement is done at the time of the setting. 


Any environment variable may be set with the directive setenv 
Example: setenv COB_LIBRARY_PATH ${LD_LIBRARY_PATH} 


Any environment variable may be unset with the directive unsetenv 
(one var per line). 
Example: unsetenv COB_LIBRARY_PATH 


Runtime configuration files can include other files with the directive 
include. 
Example: include my-runtime-configuration-file 


To include another configuration file only if it is present use the directive 
includeif. 

You can also use ${envvar} inside this. 

Example: includeif ${HOME}/mygc.cfg 


If you want to reset a parameter to its default value use: 
reset parametername 


Most runtime variables have boolean values, some are switches, some have 
string values, integer values and some are size values. 
The boolean values will be evaluated as following: 

to true: 1, Y, ON, YES, TRUE (no matter of case) 

to false: O, N, OFF 
A ’size’ value is an integer optionally followed by K, M, or G for kilo, mega 
or giga. 


For convenience a parameter in the runtime.cfg file may be defined by using 
either the environment variable name or the parameter name. 

In most cases the environment variable name is the parameter name (in upper 
case) with the prefix COB_ 


Note: If you want to *slightly* speed up a program’s startup time, remove all 
of the comments from the actual real configuration file that is processed 


10.2.3.2. General Environment 


Environment name: COB_DISABLE_WARNINGS 
Parameter name: disable_warnings 
Purpose: turn off runtime warning messages 
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Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 
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boolean 
false 
DISABLE_WARNINGS TRUE 


COB_ENV_MANGLE 

env_mangle 

names checked in the environment would get non alphanumeric 
change to ’_?’ 

boolean 

false 

ENV_MANGLE TRUE 


COB_SET_DEBUG 

debugging _mode 

to enable USE ON DEBUGGING procedures that were active 
during compile-time because of WITH DEBUGGING MODE, 
otherwise the code generated will be skipped 

boolean 

false 

COB_SET_DEBUG 1 


COB_SET_TRACE 

set_trace 

to enable COBOL trace feature 
boolean 

false 

SET_TRACE TRUE 


COB_TRACE_FILE 

trace_file 

to define where COBOL trace output should go 
string 

stderr 

TRACE_FILE ${HOME}/mytrace.log 


COB_TRACE_FORMAT 

trace_format 

to define format of COBOL trace output 

string 

"ZP 45 Line: %L" 

“%P is replaced by Program-Id/Function-Id minimal length 29 
with prefix 

41 is replaced by Program-Id/Function-Id variable length, 
without prefix 

%L is replaced by Line number, right justified, length 6 

“8 is replaced by statement type and name 
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Example: 
Note: 


For v4.0+ 
Environment name: 

Parameter name: 
Purpose: 
Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 

Note: 

Type: 

Default: 

Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


For v4.0+ 
Environment name: 

Parameter name: 
Purpose: 
Type: 
Default: 
Example: 


For v4.0+ 
Environment name: 
Parameter name: 

Purpose: 


Type: 
Default: 


Example: 


Environment name: 
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“%F is replaced by source file name 
TRACE_FORMAT "Line: %L 7%S" 
format of GC2.2 and older: 


"PROGRAM-ID: %I Line: 4%L 48" 


COB_TRACE_IO 
trace_io 
define if I/0 details should be added to trace 
boolean 
false 
TRACE_IO true 


COB_DUMP_FILE 

dump_file 

to define where COBOL dump output should go 

The -fdump=all compile option prepares for dump 
string : $$ is replaced by process id 
stderr 

DUMP_FILE ${HOME}/mytrace.log 


COB_DUMP_WIDTH 

dump_width 

to define COBOL dump line length 
integer 

100 

dump_width 120 


COB_STATS_RECORD 
stats_record 
define if I/0 statistics should be written 
boolean 
false 
STATS_RECORD true 


COB_STATS_FILE 
stats_file 
to define where COBOL I/0 statistics should be written 
The file is appended to 
string 
stderr 
STATS_FILE ${HOME}/mystats.txt 


COB_CURRENT_DATE 
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Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


current_date 

specify an alternate Date/Time to be returned to ACCEPT 
clauses this is used for testing purposes or to tweak 

a missing offset partial setting is allowed 

numeric string in format YYYYDDMMHH24MISS or date string 
the operating system date is used 

COB_CURRENT_DATE "2016/03/16 16:40:52" 

current_date YYYYMMDDHHMMSS+01:00 


10.2.3.3. Call Environment 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Note: 


Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Note: 


Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


Environment name: 


Parameter name: 
Purpose: 


Alias: 
Type: 
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COB_LIBRARY_PATH 

library_path 

paths for dynamically-loadable modules 

string 

the default paths .:/installpath/extras are always 
added to the given paths 

LIBRARY_PATH /opt/myapp/test : /opt/myapp/production 


COB_PRE_LOAD 

pre_load 

modules that are loaded during startup, can be used 

to CALL COBOL programs or C functions that are part 

of a module library 

string 

the modules listed should NOT include extensions, the 
runtime will use the right ones on the various platforms, 
COB_LIBRARY_PATH is used to locate the modules 

PRE_LOAD COBOL_function_library:external_c_library 


COB_LOAD_CASE 


load_case 
resolve ALL called program names to UPPER or LOWER case 
Only use UPPER or LOWER 


if not set program names in CALL are case sensitive 
LOAD_CASE UPPER 


COB_PHYSICAL_CANCEL 

physical_cancel 

physically unload a dynamically-loadable module on CANCEL, 
this frees some RAM and allows the change of modules during 
run-time but needs more time to resolve CALLs (both to 
active and not-active programs) 

default_cancel_mode, LOGICAL_CANCELS (0 = yes) 

boolean (evaluated for true only) 
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Default: false 
Example: PHYSICAL_CANCEL TRUE 


10.2.3.4. File I/O 


Environment name: COB_VARSEQ FORMAT 
Parameter name: varseq_format 
Purpose: declare format used for variable length sequential files 
- different types and lengths precede each record 
- ?length’ is the data length, does not include the prefix 


Type: O means 2 byte record length (big-endian) + 2 NULs 
1 means 4 byte record length (big-endian) 
2 means 4 byte record length (local machine int) 
3 means 2 byte record length (big-endian) 
Default: 0 


Example: VARSEQ_FORMAT 1 


For v4.0+ 
Environment name: COB_VARREL_FORMAT 
Parameter name: varrel_format 
Purpose: declare format to be used for variable length relative files 
Type: gc means ’size_t’ record length (local machine) precedes 
maxiumum length data record 
mf means file is in Micro Focus format 
b32 means Big-Endian 32-bit ’int’ record length precedes data 
b64 means Big-Endian 64-bit ’int’ record length precedes data 
132 means Little-Endian 32-bit ’int’ record length precedes data 
164 means Little-Endian 64-bit ’int’ record length precedes data 
Default: gc 
NOTE: ’gc’ results in files which cannot be used if copied between 
machines of different hardware archeticture 
Example: VARREL_FORMAT mf 


For v4.0+ 
Environment name: COB_FIXREL_FORMAT 
Parameter name: fixrel_format 
Purpose: declare format to be used for fixed length relative 
files (different types and lengths preceding each record) 
Type: b32 means 4 byte record length (big-endian) 

132 means 4 byte record length (little-endian) 
b64 means 8 byte record length (big-endian) 
164 means 8 byte record length (little-endian) 
mf means Micro Focus default 
gc means GnuCOBOL default (local ’size_t’) 
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Default: gc fixed size with no record length prefix 
Example: FIXREL_FORMAT B32 


For v4.0+ 
Environment name: COB_VARFIX_FORMAT 
Parameter name: varfix_format 
Purpose: declare format to be used for fixed length relative files 
Type: gc means ’size_t’ record length (local machine) precedes 
fixed length data record 
mf means file is in Micro Focus format 
b32 means Big-Endian 32-bit ’int’ record length precedes data 
b64 means Big-Endian 64-bit ’int’ record length precedes data 
132 means Little-Endian 32-bit ’int’ record length precedes data 
164 means Little-Endian 64-bit ’int’ record length precedes data 
Default: gc 
NOTE: ’gc’ results in files which cannot be used if copied between 
machines of different hardware archeticture 
Example: VARFIX_FORMAT mf 


Environment name: COB_FILE_PATH 
Parameter name: file_path 
Purpose: define default location where data files are stored 
Type: file path directory 
Default: . (current directory) 
Example: FILE_PATH ${HOME}/mydata 


Environment name: COB_LS_FIXED 
Parameter name: l1s_fixed 
Purpose: Defines if LINE SEQUENTIAL files should be fixed length 
(or variable, by removing trailing spaces) 

Alias: STRIP_TRAILING_SPACES (0 = yes) 
Type: boolean 

Default: false 

Example: LS_FIXED TRUE 


Environment name: COB_LS_NULLS 
Parameter name: l1s_nulls 
Purpose: Defines for LINE SEQUENTIAL files what to do with data 
which is not DISPLAY type. This could happen if a LINE 
SEQUENTIAL record has BINARY/COMP data fields in it. 
For v4.0+ (may change before its release candidate) 
This option is only for GnuCOBOL format files 
Type: boolean 
Default: false 
Note: The TRUE setting will insert a null character x"00" before 
those values to escape them, and redo on read-in. 
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Example: 


For v4.0+ 
Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 


Example: 


For v4.0+ 
Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Note: 


Example: 
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LS_NULL = TRUE 


COB_LS_SPLIT 

ls_split 

Defines for LINE SEQUENTIAL files what to do when a record 
is longer than the program handles. If ’1ls_split=true’ then 
the data is returned as multiple records 

boolean 

false 

The record is truncated and the file skips to the next LF 
LS_SPLIT = TRUE 


COB_LS_VALIDATE 

ls_validate 

Defines for LINE SEQUENTIAL files that the data should be 
validated. If any record has non-DISPLAY characters then 
an error status of 34 is returned 

For v4.0+ (may change before its release candidate) 

This option is only for GnuCOBOL format files 

boolean 

true 

The TRUE setting does data validation 

The FALSE setting lets non-DISPLAY characters be written 
If LS_NULLS is set, then LS_VALIDATE is not checked 
LS_VALIDATE = FALSE 


For v4.0+ (may be replaced before its release candidate) 


Environment name: 


COB_MF_FILES 


Parameter name: mf_files 


Purpose: 


Type: 
Default: 
Example: 


Declares that all files in the program should be in 
Micro Focus compatible format. 

boolean (evaluated for true only) 

false 

mf_files True 


For v4.0+ (may be replaced before its release candidate) 


Environment name: 


Parameter name: 
Purpose: 


Type: 
Default: 
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COB_MF_LS_NULLS 
mf_ls_nulls 
Defines for Micro Focus compatible LINE SEQUENTIAL files 
what to do with data which is not DISPLAY type. 
This could happen if a LINE SEQUENTIAL record has 
BINARY/COMP data fields in it. 
boolean 
true 
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Note: 
Example: 


For v4.0+ (may be 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


For v4.0+ (may be 


Environment name: 


Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


For v4.0+ (may be 


Environment name: 


Parameter name: 
Purpose: 


Type: 
Default: 
Note: 


Example: 


For v4.0+ 


Environment name: 


Parameter name: 
Purpose: 


Type: 


The TRUE setting will handle files that contain COMP data 
in a similar manner to the method used by Micro Focus COBOL 
MF_LS_NULLS = TRUE 


replaced before its release candidate) 
COB_MF_LS_INSTAB 
mf_ls_instab 
Defines for LINE SEQUENTIAL files that multiple spaces 
should be replaced by a TAB character, assuming a ’tab set’ 
value of 8. Each TAB means to skip to the next column that 
is a multiple of 8 
Similar to Micro Focus INSERTTAB=O0N option 
boolean 
false 
MF_LS_INSTAB = TRUE 


replaced before its release candidate) 
COB_MF_LS_SPLIT 
mf_ls_split 
Defines for Micro Focus compatible LINE SEQUENTIAL files what 
to do when a record is longer than the program handles. 
If ’mf_ls_split=true’ then 
the data is returned as multiple records 
boolean 
true 
MF_LS_SPLIT = FALSE 


replaced before its release candidate) 
COB_MF_LS_VALIDATE 
mf_ls_validate 
Defines for Micro Focus compatible LINE SEQUENTIAL files 
that the data should be validated. 
If any record has non-DISPLAY characters then 
an error status of 34 is returned 
boolean 
false 
The TRUE setting does data validation 
The FALSE setting lets non-DISPLAY characters be written 
If MF_LS_NULLS is set, then MF_LS_VALIDATE is not checked 
MF_LS_VALIDATE = FALSE 


COB_SHARE_MODE 

share_mode 
Defines what file sharing option should be used 
-- choice of values --- 
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none - nothing overrides application code 
read - files opened as SHARE READ ONLY 
all - files opened as SHARE ALL OTHERS 
no - files opened as SHARE NO OTHERS 
Default: none 
Example: share_mode = ALL 


For v4.0+ 
Environment name: COB_RETRY_MODE 
Parameter name: retry_mode 
Purpose: Defines what I/0 retry sharing option should be used 


Type: --- choice of values --- 
none - nothing overrides application code 
never - I/O is never retried 


forever - I/0 will be retried until success 
Default: none 
Example: retry_mode = never 


For v4.0+ 
Environment name: COB_RETRY_TIMES 
Parameter name: retry_times 
Purpose: Defines how many times I/0 should be retried 
Type: integer 
Default: 0 
Example: retry_times = 10 


For v4.0+ 
Environment name: COB_RETRY_SECONDS 
Parameter name: retry_seconds 
Purpose: Defines how many seconds I/0 should be retried 
Type: integer 
Default: 0 
Example: retry_seconds = 6 


For v4.0+ 
Environment name: COB_KEYCHECK 
Parameter name: keycheck 
Purpose: Must INDEXED file keys match COBOL SELECT exactly 
Type: boolean 
Default: true 
Example: keycheck = off 


Environment name: COB_SYNC 
Parameter name: sync 
Purpose: Should the file be synced to disk after each write/update 
Type: boolean 
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Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


false 
SYNC: TRUE 


COB_SORT_MEMORY 

sort_memory 

Defines how much RAM to assign for sorting data 
if this size is exceeded the SORT will be done 
on disk instead of memory 

size but must be more than 1M 

128M 

SORT_MEMORY 64M 


COB_SORT_CHUNK 

sort_chunk 

Defines how much RAM to assign for sorting data in chunks 
size but must be within 128K and 16M 

256K 

SORT_CHUNK 1M 


10.2.3.5. Screen I/O 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Note: 

Example: 


Environment name: 
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COB_BELL 

bell 

Defines how a request for the screen to beep is handled 
FLASH, SPEAKER, FALSE, BEEP 

BEEP 

BELL SPEAKER 


COB_REDIRECT_DISPLAY 

redirect_display 

Defines if DISPLAY output should be sent to ’stderr’ 
boolean 

false 

redirect_display Yes 


COB_SCREEN_ESC 

screen_esc 

Enable handling of ESC key during ACCEPT 

boolean 

false 

is only evaluated if COB_SCREEN_EXCEPTIONS is active 
screen_esc Yes 


COB_SCREEN_EXCEPTIONS 
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Parameter name: 
Purpose: 

Type: 

Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 


Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 

Type: 

Default: 

Note: 

Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Note: 


Alias: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Note: 


15 January 2023 


667 


screen_exceptions 

enable exceptions for function keys during ACCEPT 
boolean 

false 

screen_exceptions Yes 


COB_TIMEOUT_SCALE 

timeout_scale 

specify translation in milliseconds for ACCEPT clauses 
BEFORE TIME value / AFTER TIMEOUT 

integer 

O means 1000 (Micro Focus COBOL compatible), 1 means 100 
(ACUCOBOL compatible), 2 means 10, 3 means 1 

0 

timeout_scale 3 


COB_INSERT_MODE 

insert_mode 

specify default insert mode for ACCEPT; O=off, 1=on 
boolean 

false 

also sets the cursor type (if available) 
insert_mode Y 


COB_MOUSE_FLAGS 
mouse_flags 

specify which mouse events will be sent as function key 
to the application during ACCEPT and how they will be 
handled 

int (by bits) 

1 

O disables the mouse cursor, any other value enables it, 
any value containing 1 will enable internal handling (click 
to position, double-click to enter). 

See copy/screenio.cpy for list of events and their values. 
MOUSE_FLAGS 

11 (enable internal handling => 1, left press => 2, 

double-click => 8; 1+2+8=11) 

COB_MOUSE_INTERVAL 
mouse_interval 

specifies the maximum time (in thousands of a second) 
that can elapse between press and release events for them 
to be recognized as a click. 

int (0 - 166) 

100 

0 disables the click resolution (instead press + release 
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are recognized), also disables positioning by mouse click 


Environment name: COB_DISPLAY_PRINT_PIPE 
Parameter name: display_print_pipe 
Purpose: Defines command line used for sending output of 
DISPLAY UPON PRINTER to (via pipe) 
This is very similar to Micro Focus COBPRINTER 
Note: Each executed DISPLAY UPON PRINTER statement causes a 
new invocation of command-line (= new process start). 
Each invocation receives the data referenced in 
the DISPLAY statement and is followed by an 
end-of-file condition. 
COB_DISPLAY_PRINT_FILE, if set, takes precedence 
over COB_DISPLAY_PRINT_PIPE. 
Alias: COBPRINTER 
Type: string 
Default: not set 
Example: print ’cat >>/tmp/myprt.log’ 


Environment name: COB_DISPLAY_PRINT_FILE 
Parameter name: display_print_file 
Purpose: Defines file to be appended to by DISPLAY UPON PRINTER 
Note: Each DISPLAY UPON PRINTER opens, appends and closes the file. 
Type: string : $$ is replaced by process id 
Default: not set 
Example: display_printer ’/tmp/myprt.log’ 


Environment name: COB_DISPLAY_PUNCH_FILE 
Parameter name: display_punch_file 
Purpose: Defines file to be created on first 
DISPLAY UPON SYSPUNCH/SYSPCH 
Note: The file will be only be closed on runtime exit. 
Type: string : $$ is replaced by process id 
Default: not set 
Example: display_punch ’./punch_$$.out’ 


Environment name: COB_LEGACY 
Parameter name: legacy 
Purpose: keep behaviour of former runtime versions, currently only 
for setting screen attributes for non input fields 
Type: boolean 
Default: not set 
Example: legacy true 


Environment name: COB_EXIT_WAIT 
Parameter name: exit_wait 
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Purpose: 


Type: 
Default: 
Example: 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


to wait on main program exit if an extended screenio 
DISPLAY was issued without an ACCEPT following 
boolean 

true 

COB_EXIT_WAIT off 


COB_EXIT_MSG 

exit_msg 

string to display if COB_EXIT_WAIT is processed, set to ’@w{}’ 
if no actual display but an ACCEPT should be done 

string 

?end of program, please press a key to exit’ 
COB_EXIT_MSG ’@w{}’ 


(localized) 


10.2.3.6. Report I/O 


Environment name: 
Parameter name: 
Purpose: 


Type: 
Default: 
Example: 


COB_COL_JUST_LRC 

col_just_lrc 

If true, then COLUMN defined as LEFT, RIGHT or CENTER 

will have the data justified within the field limits 

If false, then the data is just copied into the column as is 
boolean 

TRUE 

col_just_lrce True 


10.2.3.7. File I/O Environment Variables and/or dictionary file 


GnuCOBOL 4.+ only! 


Before a file is opened a check is done for environment variables that 

may define various attributes of the file 

First a check is made for attributes for files of the same ORGANIZATION 
IX_OPTIONS for INDEXED, SQ_OPTIONS for SEQUENTIAL, RL_OPTIONS for RELATIVE 
LS_OPTIONS for LINE SEQUENTIAL, LA_OPTIONS for LINE ADVANCING SEQUENTIAL 
If none of these are present, it then checks for IO_OPTIONS 


Then an additional check is done for I0_asgnmame where ’asgname’ was 
the ASSIGN EXTERNAL name used in the program 


The environment variable (or dictionary file) may contain any of the 
following keywords, separated by spaces and/or commas 


You can specify just the keyword and it is assumed to mean set to true, 
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or no-keyword (or no_keyword or nokeyword) which means set to false, 


or keyword=true or keyword=false. 


Keyword 


type=xx 


mf 

ge 

recsz 
maxsz 
minsz 
ls_nulls 


ls_validate 
crlf 

1f 

sync 

B32 

L32 

B64 

L64 

trace 

stats 
retry_times 
retry_seconds 
retry_forever 
retry_never 
ignore_lock 
advancing_lock 
share_all 
share_read 
share_no 


The valid keywords are: 
Meaning 


Set file organization where ’xx’ is one of 

IX = INDEXED, SQ = SEQUENTIAL, RL = RELATIVE 

LS = LINE SEQUENTIAL, LA = LINE ADVANCING 

Set file to Micro Focus compatible format 

Set to original GnuCOBOL default format 

The size for fixed size record file 

Maximum record size for variable length records 

Minimum record size for variable length records 

Do NUL insertion before characters less than a SPACE, 
Default: false 

Validate data for LINE Sequential Files, Default: true 
Lines end with CR LF (Windows format for text files) 

Lines end with LF (Unix format for text files) 

Sync all writes to disk 

Use 32-bit Big-Endian format ’int’ as record length 

Use 32-bit Little-Endian format ’int’ as record length 

Use 64-bit Big-Endian format ’int’ or ’size_t’ as record length 
Use 64-bit Little-Endian format ’int’ or ’size_t’ as record length 
Enable I/0 trace when program execution tracing is enabled 
Write I/O statistic information on file close 

Default number of times to retry I/0 

Number of seconds between I/O retry attempts 

Retry I/O forever 

Never retry I/0 operations 

Ignore record locks 

Advance to the next record if lock condition 

Share file with ALL others 

Share file for READ only 

Share file with NO others 


---- For INDEXED files ----- 
format=ixhandler INDEXED file format: CISAM,DISAM,VBISAM,BDB,LMDB 


format=auto 
nkeys=n 
key1=(loc:1len) 


INDEXED file format is determined by inspecting the file 
number of indexes 
loc (zero relative) of key, len of key 


key2=(loc:len,loc:len ...) 


dupn=Y 


define composite index 
index allows dups 


---- For INDEXED BDB files ----- 


big_endian 
little_endian 
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Set internal ’int’ byte order to BIG ENDIAN 
Set internal ’int’ byte order to LITTLE ENDIAN 
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10.2.4. Program Arguments 


Regardless of the manner in which a main program is executed (i.e. directly or via cobcrun), 
any arguments specified to the program may be retrieved via any of the following: 


e ACCEPT FROM COMMAND-LINE (see [ACCEPT FROM COMMAND-LINE], page 269) 


e PROCEDURE DIVISION CHAINING (see [PROCEDURE DIVISION CHAINING], 
page 250) 


10.3. Binary Truncation 


By default, the GnuCOBOL compiler will truncate binary data items to the precision indi- 
cated by their PICTURE (see [PICTURE], page 194) clause, if they have one. This applies 
to COMP, BINARY and COMP-4 items Only. 

The fact is, however, that binary truncation has a significant effect on the performance 
of GnuCOBOL programs. When binary truncation is in effect, arithmetic operations per- 
formed against all types of numeric data items (even USAGE DISPLAY) are slowed down. 


Before continuing, it’s worth making the point that we’re not talking about astronomical 
performance degradations here. Today’s computers are fast, and a user sitting at the key- 
board, running a GnuCOBOL program is unlikely to notice. But, if you have a GnuCOBOL 
program that has to process large amounts of data, performing some significant “number 
crunching” against that data as it goes, the impact of truncation could become noticeable. 


The following program compares the performance of performing arithmetic operations 
(in a totally non-scientific, non-rigorous way) against data items with a USAGE (see [USAGE], 
page 232) of DISPLAY, COMP and BINARY-LONG. It was actually my intent when I first wrote 
the program to merely demonstrate the relative performance differences between different 
types of numeric data storage, and it certainly met that objective. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEMOMATH. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 Begin-Time. 


05 BT-HH PIC 9(2). 

05 BI-MM PIC 9(2). 

05 BTI-SS PIC 9(2). 

05 BT-HU PIC 9(2). 
01 Binary-Item BINARY-LONG SIGNED VALUE 0. 
01 Comp-Item COMP PIC S9(9) VALUE 0. 
01 Display-Item DISPLAY PIC S9(9) VALUE 0. 
O1 End-Time. 

05 ET-HH PIC 9(2). 

05 ET-MM PIC 9(2). 

05 ET-SS PIC 9(2). 

05 ET-HU PIC 9(2). 
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78 Repeat-Count VALUE 10000000. 
01 Time-Diff PIC 229.99. 
PROCEDURE DIVISION. 
010-Test-Usage-DISPLAY. 

ACCEPT Begin-Time FROM TIME 

PERFORM Repeat-Count TIMES 

ADD 7 TO Display-Item 

END-PERFORM 

PERFORM 100-Determine-Time-Diff 

DISPLAY ’USAGE DISPLAY: ’ Time-Diff ’ SECONDS’ 


020-Test-Usage-COMP . 
ACCEPT Begin-Time FROM TIME 
PERFORM Repeat-Count TIMES 
ADD 7 TO Comp-Item 
END-PERFORM 
PERFORM 100-Determine-Time-Diff 
DISPLAY ’USAGE COMP: > Time-Diff ’ SECONDS’ 


040-Test-Usage-BINARY. 
ACCEPT Begin-Time FROM TIME 
PERFORM Repeat-Count TIMES 
ADD 7 TO Binary-Item 
END-PERFORM 
PERFORM 100-Determine-Time-Diff 
DISPLAY ’USAGE BINARY: ’ Time-Diff ’ SECONDS’ 


099-Done. 
STOP RUN 


100-Determine-Time-Diff. 
ACCEPT End-Time FROM TIME 
COMPUTE Time-Diff = 
( (ET-HH * 360000 + ET-MM * 6000 + ET-SS * 100 + ET-HU) 
- (BT-HH * 360000 + BT-MM * 6000 + BT-SS * 100 + BT-HU) ) 
/ 100 


Each data item has 7 added to it ten million times. 


The time (to one-one-hundredth of a second) will be retrieved before and after each test 
and the difference between the two is displayed. This is why the computations were done 
so many times — it was to make sure the timing was measurable with only a 1/100 second 
“stopwatch”. 
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I also ran the tests multiple times, just to make sure I had consistent results (I did). Like 
I mentioned earlier, this is not a rigorous, scientific benchmark of numeric performance; it’s 
just a quick-and-dirty comparison. 


Here are the results: 


Test 1: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


Test 2: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


Test 3: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


72 
.62 
.02 


.69 
61 
.02 


.69 
.65 
.02 


SECONDS 
SECONDS 
SECONDS 


SECONDS 
SECONDS 
SECONDS 


SECONDS 
SECONDS 
SECONDS 


The results I saw here were consistent with those that would have been obtained from most 
of the COBOL implementations I have ever worked with — USAGE COMP has a significant 
performance advantage over USAGE DISPLAY and USAGE BINARY-LONG (and presumably the 
other BINARY-xxx usages as well) perform identically, within the measurement tolerances 


of the test. 


Imagine my surprise, however, when I discovered that the use of -fnotrunc switch also 


made a difference: 


Test 4: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


Test 5: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


Test 6: 

USAGE DISPLAY: 
USAGE COMP: 
USAGE BINARY: 


je) 


72 
.O7 
.02 


72 


0.07 


.02 


13 
.06 
.02 


SECONDS 
SECONDS 
SECONDS 


SECONDS 
SECONDS 
SECONDS 


SECONDS 
SECONDS 
SECONDS 


As you can see, there was a huge drop in USAGE COMP timings by turning off truncation. As 
a result, I see absolutely no reason whatsoever why the -fnotrunc switch option shouldn’t 


be used on all GnuCOBOL compilations. 


15 January 2023 
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If you want to squeeze every last bit of performance out of your GnuCOBOL programs, 
don’t forget to investigate the -O switch, -02 switch and the -Os switch, all of 
which influence the optimization of compiled code. Actually run programs using various 
optimization switches (or not) and compare execution times against those of unoptimized 
compiled versions of your programs. Don’t just compare the generated C code because 
sometimes the differences can’t be seen at the C source-code level. 

Test 7: 
cobc -x demomath.cbl -02;demomath 
USAGE DISPLAY: 1.68 SECONDS 


USAGE COMP: 0.60 SECONDS 
USAGE BINARY: 0.00 SECONDS 
Test 8: 


cobc -x demomath.cbl -fnotrunc -02;demomath 
USAGE DISPLAY: 1.67 SECONDS 
USAGE COMP: 0.01 SECONDS 
USAGE BINARY: 0.00 SECONDS 


All tests above carried out under Linux with a AMD F'X8350 under very low loading prior 
to the test. I would have also tried on a i7-7700 but that is under Windows 10 and I do not 
have a GC version on it - Vince. 


End of Chapter 10 — Interfacing With The OS 
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11. Sub-Programming 


11.1. Subprogram Types 


Simply stated, a Subprogram is a program that is invoked by another program; the sub- 
program performs whatever its designed operations are and — when complete — typically 
returns control back to the program that invoked it. There are two different types of subpro- 
grams supported by GnuCOBOL, subroutines and user-defined functions. The distinction 
between these two subprogram types lies in the manner in which they are executed. 


When program A invokes subprogram B as a Subroutine, it does so using a special 
statement dedicated to that function (the CALL statement (see [CALL], page 293), just as 
if B were one of the built-in system subroutines. 


When program A invokes program B asa User-Defined Function, it does so in a manner 
identical to how B would have been invoked had it been one of the many built-in intrinsic 
functions. 


In either instance, program A is referred to as the Calling Program while program B is 
known as the Called Program. GnuCOBOL programs may be a calling program, a called 
program or both. 


A program written in the C programming language may serve as either the calling or 
called program too. A called program may act as a calling program to another called 
program. When a calling program does not serve as a called program to any program, that 
calling program is known as a Main Program. 


Both subroutines and user-defined functions may return a value. The value they return 
must be an integer in the range -2147483648 to +2147483647. This value will be available in 
the RETURN-CODE special register (see [Special Registers], page 265) and also as the value 
of the data item specified on the RETURNING (see [CALL], page 293) clause of a subroutine’s 
CALL. 


11.2. Independent vs Contained vs Nested Subprograms 


Subprograms (either subroutines or user-defined functions) can be implemented in three 
different ways. 


Independent Subprograms 
These are subprograms that are coded as the only COBOL program in their 
Compilation Unit (see [Compilation Unit], page 636). 


Contained Subprograms 
These are subprograms which occur in the same Compilation Unit as a main 
program and/or other subprograms. Each contained subprogram is separated 
from the next via an END PROGRAM marker line. As an example... 
IDENTIFICATION DIVISION. 
PROGRAM-ID. SUB1. 


END PROGRAM SUB1. 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. SUB2. 


END PROGRAM SUB2. 


Program source code may be concatenated as shown here, provided an END 
PROGRAM marker naming the PROGRAM-ID of the just-completed program is used 
to separate one program from another. 


There’s no reason that user-defined functions cannot be included too — they'll 
just have FUNCTION-IDs and will be ended by END FUNCTION markers. 
The last program in any GnuCOBOL source file need not have an END marker. 


When multiple programs occur in a source file, it is assumed that the programs 
are related to one another in that they will be CALLed or executed as functions 
from the others. 


Nested Subprograms 


It is also possible to create source files where GnuCOBOL programs are nested 
inside each other. Take for example these four GnuCOBOL programs: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. PROG1. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. PROG2. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. PROG3. 


END PROGRAM PROG3. 
END PROGRAM PROG2. 
IDENTIFICATION DIVISION. 
PROGRAM-ID. PROG4. 


END PROGRAM PROG4. 
END PROGRAM PROG1. 


Here we see that PROG2 is nested inside of PROG1 because there is no END 
PROGRAM marker separating them. This means that data items or files defined 
within PROG1 can be used within PROG2 simply by attaching the GLOBAL (see 
[GLOBAL], page 176) attribute to them back in PROG1 when they are defined. 


Similarly, since there is no END PROGRAM marker separating PROG3 from PROG2, it 
is possible for PROG3 to access GLOBAL files and data items defined within PROG2. 
Since PROG2 is nested within PROG1, any GLOBAL resources defined within PROG1 
will be available to PROG3 as well. 


The two END PROGRAM markers for PROG3 and PROG2 (note their sequence) mean 
that PROG4 is nested within PROG1 only. It will not have access to any GLOBAL 
resources defined within either PROG2 or PROG3. 


Chapter 11 - Sub-Programming 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 677 


The END PROGRAM PROG1. marker, since it is the last line in the source file, is 
entirely optional. 


11.3. Alternate Entry Points 


Any subroutine may have multiple entry-points defined within it. This means the subroutine 
could be called either via a CALL ’ program-id’ or aCALL ’entry-point’ statement. There 
may be any number of alternate entry-points defined within a subroutine. 

Alternate entry-points provide multiple ways in which the same subroutine may be 
called; presumably, each entry-point will provide some different functionality to the calling 
program. For example, if you wished to write a subroutine that manipulates "student" 
records in a database, you might have the primary entry-point name retrieve a student 
record from the database, while the alternate entry points Add-Student, Update-Student 
and Delete-Student could provide the alternate functions implied by their entry-point 
names. 

The alternative to using multiple entry points in your subroutine, by the way, would be 
to include an additional argument to the primary (and only) entry point of the subroutine; 
this new argument might be named STUDENT-FUNCTION and might have values of ‘FETCH’, 
‘ADD’, ‘UPDATE’ or ‘DELETE’. 

The primary entry-point for any subroutine is always the first executable statement 
following any DECLARATIVES (see [DECLARATIVES], page 254) in the procedure division. 
The name of that entry-point (the name that will be called) is the subroutine’s PROGRAM-ID 
(see [IDENTIFICATION DIVISION], page 85). 

An alternate entry point is added to a subroutine using the ENTRY statement (see 
[ENTRY], page 318). 

When an alternate entry-point is called, execution within the subroutine will begin at 
the first executable statement following the ENTRY statement. 


11.4. Dynamic vs Static Subprograms 


Any subprogram may be either statically or dynamically loaded into memory. 

A Static Subprogram is one which was in the same Compilation Unit (see [Compilation 
Unit], page 636) as the other program(s) which call it, therefore meaning that its executable 
object code is part of the same executable file as its calling program. The static subprogram 
was therefore loaded into memory as part of and at the same time as the calling program. 

A Dynamic Subprogram is one whose executable object code exists as an executable file 
separate from that containing the calling program; these two programs were therefore each 
compiled in their own separate Compilation Group (see [Compilation Group], page 636). 
Dynamic subprograms are located and loaded into memory the first time they are exe- 
cuted. Dynamic subprograms may be unloaded from memory via the CANCEL statement 
(see [CANCEL], page 298), if desired. 

GnuCOBOL subprograms may be created as either static or dynamic subprograms, as 
desired by the programmer. 

To demonstrate, assume that a GnuCOBOL Main Program (whose code resides in the 
file M.cb1) will be calling three subprograms, named A, B and C (these are the PROGRAM-IDs 
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of the three subprograms, and their source code may be found in the files A.cb1, B.cb1 and 
C.cbl, respectively. 


Here is how these four programs would be compiled if the three subprograms are to be 
static: 


cobc -x M.cbl A.cbl B.cbl C.cbl 


This command informs the compiler (cobc) that four programs are to be compiled (the 
first named on the command must always be the main program), and a single executable 
file is to be created (due to the -x switch). 


Here is how the main program and the three subprograms could be compiled if the three 
subprograms are to be dynamic: 


cobc -x M.cbl 
cobc -m A.cbl B.cbl C.cbl 


These commands will create an executable file for the main program (-x switch) and 
three separate dynamically-loadable libraries (see -m switch), one for each of the three 
subprograms. Had we wished, we could have created a single dynamically-loadable library 
containing all three subprograms by adding the -b switch to their compilation: 


cobc -m -b A.cbl B.cbl C.cbl 


Dynamically-loadable libraries are also known by the term dynamically-loadable mod- 
ules. The two terms are synonymous. 


Here are the rules about GnuCOBOL dynamically-loadable modules: 


1. There may be multiple GnuCOBOL subprograms contained within a single 
dynamically-loadable library if the -b switch is used in addition to -m. If not, each 
subprogram will be compiled to a separate dynamically-loadable library. 


2. Dynamically-loadable modules will be named xxxxxxxx.d1l1 on a Windows system, 
XXXxXxxxx.so on a Unix system or xxxxxxxx.dylib on an OSX system, where xxxxxxxx 
exactly matches, including the usage of upper- and lower-case letters, the primary entry- 
point name (PROGRAM-ID or FUNCTION-ID) or an alternate entry point name defined via 
the ENTRY statement (see [ENTRY], page 318) of any one of the GnuCOBOL programs 
included in that module. 


3. The first time any of the GnuCOBOL subprograms in a dynamically-loadable module 
are invoked, the entry-point referenced must be the one for which the .d1l, .so or 
.dylib file is named. 


4. When a dynamically-loadable module needs to be loaded (because it is not already in 
memory from a previous subprogram execution), the dynamically-loadable library will 
be sought in the same directory from which the main program was loaded. If it cannot 
be found there, each directory named in the PATH run-time environment variable (see 
[Run Time Environment Variables], page 654) will be searched. If it was not located 
in any of those directories, the library specified by the COB_LIBRARY_PATH run-time 
environment variable will be searched. Finally, if it still cannot be located, execution 
will be terminated with an error message (libcob: Cannot find module ‘xxrrxxxx’). 


5. Once the dynamically-loadable module has been successfully loaded, any of the entry- 
points contained within it are now available for reference. 
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6. Dynamically-loadable modules may be removed from memory via the CANCEL statement 
(see [CANCEL], page 298). 


7. Once a dynamically-loadable module is actually loaded into memory, even if it is sub- 
sequently unloaded (via the CANCEL statement), its list of entry-points remain available 
to the GnuCOBOL run-time library and subsequent re-executions of any of those entry 
points will be able to bypass the search (rule #4) as well as the first-erecution rule 


(rule #3). 


Consult the documentation on the COB_PRE_LOAD run-time environment variable, 
COB_PHYSICAL_CANCEL run-time environment variable and COB_LOAD_CASE run-time envi- 
ronment variable run-time environment variables (see [Run Time Environment Variables], 
page 654) for additional options when using dynamically-loadable modules. 


11.5. Subprogram Execution Flow 


When a subprogram is invoked, the flow of execution will differ slightly depending on 
whether the subprogram is a subroutine or a user-defined function. 


11.5.1. Subroutine Execution Flow 


When a subroutine is CALLed: 


1. The calling program issues a statement of the form CALL ’entry-point’ USING ... to 
transfer control to the subroutine. 


2. The executable for the called program will be located and loaded into memory: 


A. Ifit is a static subroutine, it will already be part of the executable program issuing 
the CALL (see [CALL], page 293). 


B. If it is a dynamic subroutine, the GnuCOBOL run-time system will check to see 
if a dynamically-loadable module containing the subprogram’s entry point was 
already located. If it was, no further “location” activity is needed. If not, the 
dynamically-loadable module will be located (see [Locating Dynamically-Loadable 
Modules], page 678). 


C. Once the module has been located (if location was needed), it will be loaded into 
memory (if not already loaded). 


3. Execution of the calling program is suspended and control will transfer to the called 
program, as follows: 

A. If the PROGRAM-ID (see [IDENTIFICATION DIVISION], page 85) clause of the 
subprogram included the INITIAL clause, the program will be reinitialized back 
to its compile-time state. This will happen regardless of the INITIAL clause the 
first time the subprogram is executed. 


B. Local-storage, if any, will be allocated and initialized. 


C. Execution will begin at the first executable statement following the subprograms 
entry-point. The entry point will be either the first executable statement following 
any DECLARATIVES (see [DECLARATIVES], page 254) that might be present (if the 
subprogram was invoked using its primary entry-point name) or the first executable 
statement following the ENTRY statement (see [ENTRY], page 318) naming the 
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entry-point specified on the CALL if the subprogram was invoked using an alternate 
entry point. 


4. The flow of execution will then progress through the coding of the subprogram as it 
would with any other program. 


5. If the subprogram issues a STOP statement (see [STOP], page 399) with the RUN option, 
program execution ceases and control returns to the operating system or whatever 
execution shell invoked the main program. 


6. If the subprogram wishes to return control back to the calling program, it will do so 
using either the GOBACK statement (see [GOBACK], page 334) or the EXIT PROGRAM 
statement (see [EXIT], page 328). At this time: 


A. If the subprograms procedure division header or ENTRY statement included a 
RETURNING, the value of the data item found on that clause is moved to the 
RETURN-CODE special register (see [Special Registers], page 265); this behaviour 
can be altered utilizing the CALL-CONVENTION (see [SPECIAL-NAMES], page 92) 
feature to leave RETURN-CODE unchanged. 

B. Local-storage, if any, is de-allocated. 

C. If the calling program included a RETURNING clause on the CALL statement that 
invoked the subprogram, the value of the RETURNING data item in the subroutine 
is moved to that data item. If there was no RETURNING specified in the subroutine, 
the value of the RETURN-CODE special register is moved to that data item. 


D. Execution will resume back in the calling program with the first executable state- 
ment following the CALL that invoked the subprogram. 


11.5.2. User-Defined Function Execution Flow 


When a user-defined function is executed: 


1. The object code for the called program (the user-defined function) will be located, as 
follows: 

A. If it is a static user-defined function, it will already be part of the executable file 
containing the calling program. 

B. Ifit isa dynamic user-defined function, the GnuCOBOL run-time system will check 
to see if a dynamically-loadable module containing the function’s entry point was 
already located. If it was, no further “location” activity is needed. If not, the 
dynamically-loadable module will be located (see [Locating Dynamically-Loadable 
Modules], page 678). 

C. Once the module has been located (if location was needed), it will be loaded into 
memory (if not already loaded). 

2. Execution of the calling program is suspended and control will transfer to the called 
program, as follows: 


A. Local-storage, if any, will be allocated and initialized. 


B. Execution will begin with the first executable statement in the procedure division 
following any DECLARATIVES (see [DECLARATIVES], page 254) that might be 
present. 
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3. The flow of execution will then progress through the coding of the function as it would 
with any other program. 

4. If the function issues a STOP statement (see [STOP], page 399) with the RUN option, 
program execution ceases and control returns to the operating system or whatever 
execution shell invoked the main program. 

5. If the function wishes to return control back to the calling program, it will do so 
using either the GOBACK statement (see [GOBACK], page 334) or the EXIT FUNCTION 
statement (see [EXIT], page 328). At this time: 

A. The value of the data item found on the user-defined functions PROCEDURE 
DIVISION RETURNING (see [PROCEDURE DIVISION RETURNING], page 252) 
clause is moved to the RETURN-CODE special register (see [Special Registers], 
page 265). 

B. Local-storage, if any, is de-allocated. 

C. Execution will resume back in the calling program at the point where the returned 
value of the function is needed. At that point, the value in the RETURN-CODE 
special register will be used for the function’s value. 
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11.6. Sharing Data Between Calling and Called Programs 


11.6.1. Subprogram Arguments 


11.6.1.1. Calling Program Considerations 


Data items defined in a calling program may be passed to either type of called program 
(subroutine or user-defined function) as arguments. 


Arguments must be described in both the calling and called programs, and while they 
don’t need to have the same names in both programs, they should be described in an 
identical manner with regard to the following characteristics: 


e PICTURE (see [PICTURE], page 194) (including both type and length) 
e SIGN (see [SIGN], page 509) 

e SYNCRONIZED (see [SYNCRONIZED], page 218) 

e USAGE (see [USAGE], page 232) 


A subroutine may be passed a maximum of 251 arguments; if you build the GnuCOBOL 
software yourself from the distributed source, you CAN change this value by altering the 
defined value of COB_MAX_FIELD_PARAMS in the call.h header file but also see 7.8.5.11 
for more information. There is no built-in GnuCOBOL limit to how many arguments a 
user-defined function may be passed. 


Whether or not changes made to an argument within a subroutine will be “visible” to 
the calling program depends on how the argument was passed. There are three ways in 
which arguments may be passed from a calling program to a subroutine, as defined by the 
use of optional BY clauses in the CALL (see [CALL], page 293) statement’s list of arguments. 


As an example, the following statement passes three arguments to a subroutine — each 
argument is passed differently. 


CALL "subroutine" USING BY REFERENCE arg-1 
BY CONTENT arg-2 
BY VALUE arg-3 
END-CALL 


The three ways arguments are passed are as follows. 


BY REFERENCE 

When a subroutine argument is passed BY REFERENCE, the subroutine is passed 
the address of the actual data item being passed as an argument. The item may 
be anything defined within the data division of the program. If the subroutine 
modifies the contents of this argument, the calling program will “see” the results 
of that change when the subroutine returns control. This is the default manner 
in which GnuCOBOL passes arguments to a subroutine, should no BY clauses 
be included on the CALL. 


BY CONTENT 
When a subroutine is passed an argument BY CONTENT, the subroutine is passed 
the address of a copy of the actual data being passed as an argument. The item 
may be anything defined within the data division of the program. The copy is 
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made each time the CALL statement is executed, immediately before the CALL 
actually takes place. If the subroutine modifies the contents of this argument, it 
will be the copy that is modified, not the original data item; the calling program 
will therefore not “see” the results of that change when the subroutine returns 
control. 


BY VALUE 


Passing a subroutine argument BY VALUE passes the actual value of the data 
being passed as an argument. The item may be any elementary binary numeric 
item defined within the data division of the program. If the subroutine modifies 
the contents of this argument, the calling program will not “see” the results of 
that change when the subroutine returns control. 


The first two ways in which arguments may be passed (BY REFERENCE and BY CONTENT) 
are intended for use when a GnuCOBOL program is being called, while the first and third 
(BY REFERENCE and BY VALUE) are intended for use when a C program is being called. You 
can use BY VALUE arguments when calling GnuCOBOL subroutines, but remember that 
those arguments are limited to being a numeric binary data item. 


Arguments to user-defined functions are always passed BY REFERENCE. 


11.6.1.2. Called Program Considerations 


When coding a GnuCOBOL subprogram (a subroutine or user-defined function), all argu- 
ments to the subprogram must be defined in the subprogram’s linkage section. 

These arguments must be explicitly included on the PROCEDURE DIVISION USING (see 
[PROCEDURE DIVISION USING], page 248) clause that lists the arguments in the se- 
quence in which they will be passed to the subprogram. 

These arguments described in the PROCEDURE DIVISION USING clause may each be de- 
fined as either BY REFERENCE, if the calling program is passing them either BY REFERENCE 
or BY CONTENT, or as BY VALUE if they are being passed BY VALUE. 

By default, all arguments are assumed to be BY REFERENCE unless explicitly stated oth- 
erwise on the procedure division header. 

Arguments to a user-defined function are always to be specified as BY REFERENCE (either 
explicitly or by not using any BY). 

If the subprogram returns a value, the data item in which the value is returned must 
also be defined in the subprogram’s linkage section, with a USAGE (see [USAGE], page 232) 
of BINARY-LONG SIGNED, or its equivalent. 


11.6.2. GLOBAL Data Items 


Another way in which a data item may be shared between a calling program (A) and a 
called program (B) is by defining the data item in the calling program and attaching the 
GLOBAL (see [GLOBAL], page 176) clause to it so that it may be used within the called 
program. In order for this to work, program B (the one called by program A) must be a 
nested subprogram within program A. 
Here’s a small example: 
IDENTIFICATION DIVISION. 
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PROGRAM-ID. DemoGLOBAL. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 Arg GLOBAL PIC X(10). 
PROCEDURE DIVISION. 
000-Main. 
MOVE ALL "X" TO Arg 
CALL "DemoSub" END-CALL 
DISPLAY "DemoGLOBAL: " Arg END-DISPLAY 
GOBACK 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DemoSub. 
PROCEDURE DIVISION. 
000-Main. 
MOVE ALL "*" TO Arg. 
GOBACK 


END PROGRAM DemoSub. 
END PROGRAM DemoGLOBAL. 

When the program runs, it produces the output: 
DemoGLOBAL: 9 ********** 


11.6.3. EXTERNAL Data Items 


The final way in which a data item may be shared between a calling program (A) and a 
called program (B) is by defining the data item (with the same name) in both programs 
and attaching the EXTERNAL (see [EXTERNAL], page 171) clause to it (again, in both 
programs). This approach works regardless of whether the called program is nested within 
the calling program or not. It also works even if the two programs are compiled separately. 
Here’s a demonstration: 
IDENTIFICATION DIVISION. 
PROGRAM-ID. DemoEXTERNAL. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 Arg EXTERNAL PIC X(10). 
PROCEDURE DIVISION. 
000-Main. 
MOVE ALL "X" TO Arg 
CALL "DemoSub" END-CALL 
DISPLAY "DemoEXTERNAL: " Arg END-DISPLAY 
GOBACK 


END PROGRAM DemoEXTERNAL. 
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IDENTIFICATION DIVISION. 


PROGRAM-ID. DemoSub. 
DATA DIVISION. 


WORKING-STORAGE SECTION. 


O01 Arg EXTERNAL 
PROCEDURE DIVISION. 
000-Main. 


MOVE ALL "*" TO Arg. 


GOBACK 


END PROGRAM DemoSub. 


PIC X(10). 


When the program runs, it produces the output: 


DemoEXTERNAL: 222222222 


11.7. Recursive Subprograms 


A subroutine may CALL itself, either directly or indirectly from another subroutine or user- 
defined function that it CALLs. Any subroutine that indulges in this sort of behaviour (called 
recursion) is called a Recursive Subprogram. 

Any GnuCOBOL subroutine can be recursively invoked only if it is defined to the Gnu- 
COBOL compiler as being a recursive subroutine. This is accomplished by adding the 
RECURSIVE attribute to its PROGRAM-ID (see [IDENTIFICATION DIVISION], page 85). 


All User-defined functions are automatically capable of being executed recursively. 


Here is an example of a main program (DEMOFACT) that calls both a subprogram 
(SUB) and a user-defined function (FUNC) to compute the factorial value of a number. 


IDENTIFICATION DIVISION. 


PROGRAM-ID. DEMOFACT. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
REPOSITORY. 


FUNCTION RECURSIVEFUNC. 


DATA DIVISION. 


WORKING-STORAGE SECTION. 
O01 Result USAGE BINARY-LONG. 
O1 Arg USAGE BINARY-LONG. 


PROCEDURE DIVISION. 
000-Main. 

MOVE 6 TO Arg 

CALL "RECURSIVESUB" 


USING BY CONTENT Arg 
RETURNING Result 


DISPLAY Arg "! = " 
Result 
DISPLAY Arg "! =" 


RECURSIVEFUNC (Arg) 
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GOBACK 


END PROGRAM DEMOFACT. 

IDENTIFICATION DIVISION. 

PROGRAM-ID. SUB RECURSIVE. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

O01 Result USAGE BINARY-LONG. 

01 Next-Arg USAGE BINARY-LONG. 

01 Next-Result USAGE BINARY-LONG. 

LINKAGE SECTION. 

O01 Arg USAGE BINARY-LONG. 

PROCEDURE DIVISION USING Arg 
RETURNING Result. 


000-Main. 
DISPLAY "Entering SUB" 
" Arg="" Arg 
IF Arg = 1 


MOVE 1 TO Result 
DISPLAY "Leaving SUB" 
" Returning " Result 
ELSE 
SUBTRACT 1 FROM Arg 
GIVING Next-Arg 
CALL "SUB" 
USING BY CONTENT Next-Arg 
RETURNING Next-Result 
COMPUTE Result = 
Arg * Next-Result 
DISPLAY "Leaving SUB" 


" Returning " 
Result "=" Arg "*" 
Next-Result 
END-IF 
GOBACK 


END PROGRAM SUB. 
IDENTIFICATION DIVISION. 
FUNCTION-ID. FUNC. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
REPOSITORY. 

FUNCTION RECURSIVEFUNC. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
LINKAGE SECTION. 
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O01 Arg USAGE BINARY-LONG. 
01 Result USAGE BINARY-LONG 


SIGNED. 
PROCEDURE DIVISION US 


ING Arg 


RETURNING Result. 


000-Main. 
DISPLAY "Entering FUNC" 
" Arg="" Arg 
IF Arg = 1 
MOVE 1 TO Result 
ELSE 
COMPUTE Result = Arg * 
FUNC(Arg - 1) 
END-IF 
DISPLAY "Leaving FUNC" 
" Returning " Result 
GOBACK 


END FUNCTION FUNC. 


When DEMOFACT is executed, the output shown below is generated. 


E: \Programs\Demos>demofact 


Entering RECURSIVESUB 
Entering RECURSIVESUB 
Entering RECURSIVESUB 
Entering RECURSIVESUB 
Entering RECURSIVESUB 
Entering RECURSIVESUB 
Leaving RECURSIVESUB 
Leaving RECURSIVESUB 
Leaving RECURSIVESUB 
Leaving RECURSIVESUB 
Leaving RECURSIVESUB 
Leaving RECURSIVESUB 
+0000000006! = +00000 
Entering RECURSIVEFUN 
Entering RECURSIVEFUN 
Entering RECURSIVEFUN 
Entering RECURSIVEFUN 
Entering RECURSIVEFUN 
Entering RECURSIVEFUN 
Leaving RECURSIVEFUNC 
Leaving RECURSIVEFUNC 
Leaving RECURSIVEFUNC 
Leaving RECURSIVEFUNC 
Leaving RECURSIVEFUNC 
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Arg=+0000000006 

Arg=+0000000005 

Arg=+0000000004 

Arg=+0000000003 

Arg=+0000000002 

Arg=+0000000001 

Returning +0000000001 

Returning +0000000002=+0000000002*+0000000001 
Returning +0000000006=+0000000003*+0000000002 
Returning +0000000024=+0000000004*+0000000006 
Returning +0000000120=+0000000005*+0000000024 
Returning +0000000720=+0000000006*+0000000120 
00720 

C Arg=+0000000006 

C Arg=+0000000005 

C Arg=+0000000004 

C Arg=+0000000003 

C Arg=+0000000002 

C Arg=+0000000001 

Returning +0000000001 

Returning +0000000002 

Returning +0000000006 

Returning +0000000024 

Returning +0000000120 
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Leaving RECURSIVEFUNC Returning +0000000720 
+0000000006! = +0000000720 


11.8. Combining GnuCOBOL and C Programs 


The upcoming sections deal the issues pertaining to calling C language programs from 
GnuCOBOL programs, and vice versa. Two additional sections provide samples illustrating 
specifics as to how those issues are overcome in actual program code. 


11.8.1. GnuCOBOL Run-Time Library Requirements 


Like most other implementations of the COBOL language, GnuCOBOL utilizes a run-time 
library. When the first program executed in a given execution sequence is a GnuCOBOL 
program, any run-time library initialization will be performed by the compiled COBOL code 
in a manner that is transparent to the C-language programmer. If, however, a C program 
is the first to execute, the burden of performing GnuCOBOL run-time library initialization 
falls upon the C program. See [C Main Programs Calling GnuCOBOL Subprograms|, 
page 692, for an example of how to do this. 


11.8.2. String Allocation Differences Between GnuCOBOL and C 
Both languages store strings as a fixed-length continuous sequence of characters. 


COBOL stores these character sequences up to a specific quantity limit imposed by the 
PICTURE (see [PICTURE], page 194) clause of the data item. For example: 01 LastName 
PIC X(15).. 


There is never an issue of exactly what the length of a string contained in a USAGE 
DISPLAY (see [USAGE], page 232) data item is — there are always exactly how ever many 
characters as were allowed for by the PICTURE clause. In the example above, LastName will 
always contain exactly fifteen characters; of course, there may be anywhere from 0 to 15 
trailing SPACES as part of the current LastName value. 


C actually has no “string” data type; it stores strings as an array of char data type 
items where each element of the array is a single character. Being an array, there is an 
upper limit to how many characters may be stored in a given “string”. For example: 


char lastName[15]; /* 15 chars: lastName[0] through lastName[14] */ 


C provides a robust set of string-manipulation functions to copy strings from one char 
array to another, search strings for certain characters, compare one char array to another, 
concatenate char arrays and so forth. To make these functions possible, it was necessary to 
be able to define the logical end of a string. C accomplishes this via the expectation that 
all strings (char arrays) will be terminated by a NULL character (x’00’). Of course, no 
one forces a programmer to do this, but if [s]he ever expects to use any of the C standard 
functions to manipulate that string they had better be null-terminating their strings! 


So, GnuCOBOL programmers expecting to pass strings to or receive strings from C 
programs had best be prepared to deal with the null-termination issue, as follows: 


1. Pass a quoted literal string from GnuCOBOL to C as a zero-delimited string literal 
(Z’ string’). 
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2. Pass alphanumeric (PIC X) or alphabetic (PIC A) data items to C subroutines by ap- 
pending an ASCII NUL character (X’00’) to them. For example, to pass the 15- 
character LastName data item described above to a C subroutine: 


01 LastName-Arg-to-C PIC X(16). 


MOVE FUNCTION CONCATENATE(LastName,X’00’) TO LastName-Arg-to-C 


And then pass LastName-Arg-to-C to the C subprogram! 


3. When a COBOL program needs to process string data prepared by a C program, the 
embedded null character must be accounted for. This can easily be accomplished with 
an INSPECT statement (see [INSPECT], page 344) such as the following: 


INSPECT Data-From-a-C-Program 
REPLACING FIRST X’00’ BY SPACE 
CHARACTERS BY SPACE AFTER INITIAL X’00’ 


11.8.3. Matching C Data Types with GnuCOBOL USAGE’s 


Matching up GnuCOBOL numeric Usage’s with their C language data type equivalents is 
possible via the following chart: 
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COBOL 

BINARY-CHAR UNSIGNED 
BINARY-CHAR [ SIGNED ] 
BINARY-SHORT UNSIGNED 


BINARY-SHORT [ SIGNED |] 


BINARY-LONG UNSIGNED 


BINARY-LONG [ SIGNED ] 
BINARY-INT 


BINARY-C-LONG [ SIGNED ] 
BINARY-DOUBLE UNSIGNED 


BINARY-DOUBLE [ SIGNED | 
BINARY-LONG-LONG 
COMPUTATIONAL-1 
COMPUTATIONAL-2 


N/A (no GnuCOBOL equivalent) 


C 

unsigned char 
signed char 
unsigned 

unsigned int 
unsigned short 
unsigned short int 
int 

short 

short int 

signed int 

signed short 
signed short int 
unsigned long 
unsigned long int 
long 

long int 

signed long 

signed long int 
long 

unsigned long long 
unsigned long long int 
long long int 
signed long long int 
float 

double 

long double 


These sizes conform to the COBOL standard and the minimum sizes of the COBOL 
types are the same as the minimum sizes of the corresponding C data types. There’s no 
official compatibility between them. Note that values in square braces ’[|’ are the defaults. 


11.8.4. GnuCOBOL Main Programs CALLing C Subprograms 
Here’s a sample of a GnuCOBOL program that CALLs a C subprogram. 


COBOL Calling Program 


IDENTIFICATION DIVISION. 
PROGRAM-ID. maincob. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 Argi PIC X(7). 

01 Arg2 PIC X(7). 

01 Arg3 USAGE BINARY-LONG. 
PROCEDURE DIVISION. 

000-Main. 


DISPLAY ’Starting maincob’ 
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C Called Program 


#include <stdio.h> 
int subc(char *arg1, 
char *arg2, 
unsigned long *arg3) { 
char nui[7]="New1"; 
char nu2[7]="New2"; 
printf ("Starting subc\n") ; 
printf ("Arg1=/s\n",arg1) ; 
printf ("Arg2=/s\n" ,arg2) ; 
printf ("Arg3=/d\n" ,*arg3) ; 
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MOVE Z’Argi’ TO Argi arg1[0]=’X’; 
MOVE Z’Arg2’ TO Arg2 arg2[0]=’Y’; 
MOVE 123456789 TO Arg3 *arg3=987654321 ; 
CALL ’subc’ return 2; 

USING BY CONTENT Argi, } 


BY REFERENCE Arg2, 
BY REFERENCE Arg3 
DISPLAY ’Back’ 
DISPLAY ’Argi=’ Argi 
DISPLAY ’Arg2=’ Arg2 
DISPLAY ’Arg3=’ Arg3 
DISPLAY ’Returned value=’ 
RETURN-CODE 
STOP RUN 


The idea is to pass two string and one full-word unsigned arguments to the subprogram, 
have the subprogram print them out, change all three and pass a return code of 2 back to 
the caller. The caller will then re-display the three arguments (showing changes only to the 
two BY REFERENCE arguments), display the return code and halt. 


While simple, these two programs illustrate the techniques required quite nicely. 


Note how the COBOL program ensures that a null end-of-string terminator is present 
on both string arguments. 


Since the C program is planning on making changes to all three arguments, it declares 
all three as pointers in the function header and references the third argument as a pointer 
in the function body. It actually had no choice for the two string (char array) arguments — 
they must be defined as pointers in the function even though the function code references 
them without the leading ‘*’ that normally signifies pointers. 


These programs are compiled and executed as follows. 


$ cobc -x maincob.cbl subc.c 

$ maincob 

Starting maincob 

Starting subc 

Argi=Arg1 

Arg2=Arg2 

Arg3=123456789 

Back 

Argi=Arg1 

Arg2=Yrg2 

Arg3=+0987654321 

Returned value=+000000002 

$ 

Remember that the null characters are actually in the GnuCOBOL Arg1 and Arg2 data 

items. They don’t appear in the output, but they are there. 


Did you notice the output showing the contents of Arg1 after the subroutine was called? 
Those contents were unchanged! The subroutine definitely changed that argument, but 
since the COBOL program passed that argument BY CONTENT, the change was made to a 
copy of the argument, not to the Arg1 data item itself. 
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11.8.5. C Main Programs Calling GnuCOBOL Subprograms 


Now, the roles of the two languages in the previous section will be reversed, having a C 
main program execute a GnuCOBOL subprogram. 


C Calling Program GNU-COBOL Called Program 
#include <libcob.h> /* COB RUN-TIME */ IDENTIFICATION DIVISION. 
#include <stdio.h> PROGRAM-ID. subcob. 
int main (int argc, char **argv) { DATA DIVISION. 
int returnCode; LINKAGE SECTION. 
char argi[7] = "Arg1"; 01 Argt PIC X(7). 
char arg2[7] = "Arg2"; 01 Arg2 PIC X(7). 
unsigned long arg3 = 123456789; 01 Arg3 USAGE BINARY-LONG. 
printf ("Starting mainc...\n"); PROCEDURE DIVISION USING 
cob_init (argc, argv); /* COB RUN-TIME */ BY VALUE Argi, 
returnCode = subcob(arg1,arg2,karg3) ; BY REFERENCE Arg2, 
printf ("Back\n") ; BY REFERENCE Arg3. 
printf ("Arg1=/s\n",arg1) ; 000-Main. 
printf ("Arg2=/s\n" ,arg2) ; DISPLAY ’Starting cobsub.cbl’ 
printf ("Arg3=/d\n" ,arg3) ; DISPLAY ’Argi=’ Arg1 
printf ("Returned value=/d\n",returnCode) ; DISPLAY ’Arg2=’ Arg2 
return returnCode; DISPLAY ’?Arg3=’ Arg3 
} MOVE ’X’ TO Argi (1:1) 


MOVE ’Y’ TO Arg2 (1:1) 
MOVE 987654321 TO Arg3 
MOVE 2 TO RETURN-CODE 
GOBACK 


Since the C program is the one that will execute first, before the GnuCOBOL subroutine, 
the burden of initializing the GnuCOBOL run-time environment lies with that C program; 
it will have to invoke the cob_init function, which is part of the libcob library. The two 
required C statements are shown highlighted. 


The arguments to the cob_init routine are the argument count and value parameters 
passed to the main function when the program began execution. By passing them into 
the GnuCOBOL subprogram, it will be possible for that GnuCOBOL program to retrieve 
the command line or individual command-line arguments. If that won’t be necessary, cob_ 
init (0,NULL); could be specified instead. 


Since the C program wants to allow arg3 to be changed by the subprogram, it prefixes 
it with a ‘&’ to force a CALL BY REFERENCE for that argument. Since arg1 and arg2 are 
strings (char arrays), they are automatically passed by reference. 


Here’s the output of the compilation process as well as the program’s execution. The 

example assumes a Windows system with a GnuCOBOL build that uses the GNU C compiler 
on that system; the technique works equally well regardless of which C compiler and which 
operating system you’re using. 

C:\Users\Gary\Documents\Programs> cobc -S subcob.cbl 

C:\Users\Gary\Documents\Programs> gcc mainc.c subcob.s -o mainc.exe -llibcob 

C:\Users\Gary\Documents\Programs> mainc.exe 

Starting mainc... 

Starting cobsub.cbl 

Argi=Arg1 
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Arg2=Arg2 
Arg3=+0123456789 
Back 
Argi=Xrg1 
Arg2=Yrg2 
Arg3=987654321 
Returned value=2 
C:\Users\Gary\Documents\Programs> 
Note that even though we told GnuCOBOL that the 1st argument was to be BY VALUE, 
it was treated as if it were BY REFERENCE anyway. String (char array) arguments passed 
from C callers to GnuCOBOL subprograms will be modifiable by the subprogram. It’s best 
to pass a copy of such data if you want to ensure that the subprogram doesn’t change it. 
The third argument is different, however. Since it’s not an array you have the choice of 
passing it either BY REFERENCE or BY VALUE. 


End of Chapter 11 — Sub-Programming 


15 January 2023 Chapter 11 - Sub-Programming 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 695 


12. Programming Style Suggestions 


This chapter deals with a variety of stylistic issues that may be of interest to someone who 
is just starting out learning and using COBOL. Much of this chapter makes recommenda- 
tions and suggestions for how to write your own programs. The sample programs in the 
Sample Programs document (see Sample Programs) were coded using almost all of these 
recommendations. 


There’s no particular order of importance to the topics presented here. 


12.1. Marking Changes in Programs 


Historically in the early 60’s programs were first punched on to paper tape and by the mid 
60’s that was replaced almost totally, by punched cards although paper tape was still used 
by programmers for the odd few changes to their sources held on magnetic tape or disk as 
a portable paper tape punch could be put in your pocket. Now the problem with punched 
cards were there was 2,000 cards per box and that they could and did, get dropped. So, cc 
(column) 1 through 6 had the card sequence number in and that way if a box was dropped 
they could be feed in to a card sorter to be fixed. This was after the cards was cleaned up 
so that they were all in the same direction which one corner cut out helped. 


In the late 70’s cards was also on its way out to the point where P.C’s started being used 
(and no they were not made by IBM), so these columns could be used for other purposes 
including cc 73 - 80 instead of indicating the 8 character program name which was the 
maximum size allowed on a IBM system. 


For quite a while now (back to the late 1970’s), the sequence number area’ of a COBOL 
statement (columns 1-6) has come to be used as a change indicator area. Programmers 
would place a code in columns 1-6 of every line they changed in a program. The author 
works in a COBOL shop where change indicators of the form “xxmmyy” are required on 
every altered line of a program — “xx” is the initials of the programmer while “mmyy” 
are the month and two-digit year of the date the change was made. This is frequently 
accompanied by a comment block at or near the top of a COBOL program providing 
general documentation of what changes were made and what change indicator was used to 
mark that change. 

The GCic sample program source listing (see Section “GCic” in GnuCOBOL Sample 
Programs) provides an excellent example of such documentation. 

This technique of using columns 1-6 as a change indicator will only work if fixed source- 
record format is in effect. 

Some COBOL shops prefer to use the eight-character Program Name Area (columns 
73-80) as a change code area. 

Marking changes becomes more of a challenge when free-format source code is in effect. 
Creating a top-of-program comment block to generically describe changes that have been 
made isn’t difficult, even in free-form. What is difficult, however, is coming up with a scheme 
for per-statement mark up of changes that doesn’t introduce a ridiculously excessive number 
of source lines to the program. I’m not sure there is a good answer to this problem (if a 
reader has one, please let me know). Generally, I’ve noticed that shops using free-format 
conventions for their COBOL source tend to stick with just the top-of-program comment 
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block combined with minimal comment blocks sprinkled throughout the program noting 
areas that underwent major changes. 


12.2. Data Item Coding and Naming Conventions 


When programs get very large, it becomes more and more challenging to keep track of the 
data items that will be used in the program. Here, in no particular order of importance, 
are a variety of conventions that can simplify that problem. 


Remember that the points described here are intended to make things easier for you, 
the programmer. No COBOL compiler cares one way or another whether any of these 
suggestions are followed. 


1. Avoid the use of level 77 data items in new programs. Once (1968 and before) there 
were valid reasons for creating level-77 data items, but since the 1974 ANSI standard 
of COBOL there really hasn’t been any reason why an elementary level-01 data item 
couldn’t have been used instead of a level-77 item. 

2. Allocate level-O1 data items in alphabetical sequence in the program source wherever 
practical. This will make it vastly easier to locate the definitions of 01-level items in 
the program source without having to resort to a compilation cross-reference listing 
and/or text editor “find” command to locate them. 

3. Consider prefixing data items with an indication of where in the program structure 
they were created. For example: 

e Start everything defined in the file section with “F-” 

e Start everything defined in working-storage with “WS-” 
e Start everything defined in local-storage with “LS-” 

e Start everything defined in the linkage section with “L-” 
e Start everything defined in the screen section with “S-” 


e Start everything defined in the report section with “R-” 


A convention such as this makes it simple, when you’re reviewing code in the procedure 
division, to know in which section of the data division you should look in when locating 
the detailed description of a data item. Once you’re in the right division, coding 
convention #2 will assist in locating the data item definition. 


4. Consider including a trailing descriptor of the nature of all data items in their names. 
The following chart presents a variety of such descriptors the author has encountered 
and used through the years. 


-ADDR The data item contains all or a part of an Address (City-ADDR, 
State-ADDR, Street-ADDR, ...) 

-BOOL A level-88 data item (which only has the value TRUE or FALSE) 

-CD A code whose value denotes information content above and beyond that 
of the mere value itself. Some examples could be Error-CD, Status-CD, 
Billing-CD 

-CHR A data item containing a single character of data. 
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A constant, specified as a level-78 data item, a level-01 item with the CONST 
attribute 


The data item contains a complete or partial date (Birth-DT, 
Birth-Month-DT, Birth-Year-DT, ...) 


A data item containing both a date and a time 
A file name. Note that these items would probably also have a “F-” prefix. 
A data item used as a table index (see section 12.3) 


All or a portion of a person’s name. These could be extended to include 
business names, product names, etc. 


A data item whose USAGE is POINTER 
A generic numeric data item that doesn’t fit into any of the other categories 
A count of something 


An 01-level item defined in the FILE SECTION (constituting the layout of 
a record within a file). Note that these items would probably also have a 
“F-” prefix. 


The data item contains a complete or partial screen description (appropri- 
ate for SCREEN SECTION 01-level data items). 


A numeric item used as a table subscript (see section 12.3) 
All or part of a telephone number 
The data item contains a complete or partial time value 


The data item contains generic alphanumeric text that doesn’t fit into any 
of the other categories. 


The above is by no means an exhaustive list, but good programmers will use as few of 
these descriptors as possible as having too many defeats any benefits of such classifica- 
tion/documentation efforts. 


5. Consider including an acronym to be inserted into the name of any data item defined 
directly or indirectly subordinate to an 01-level item, typically to be specified after any 
section-level tag, if you’re using them. For example, consider the names used in the 
following structure: 


01 WS-File-Status-Message-TXT. 


05 FILLER PIC X(13) VALUE ’Status Code: °’. 
05 WS-FSM-Status-CD PIC 9(2). 
05 FILLER PIC X(11) VALUE ’, Meaning: ’. 
05 WS-FSM-Msg-TXT PIC X(25). 
01 WS-OI-SUB PIC 99 COMP. 
O01 WS-OI-IDX PIC 99 COMP. 
The “-FSM-” acronyms make it easier to locate the description of the 01-item the status 


code and message text items belong to. 
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12.3. Table Subscripting versus Table Indexing 


The elements of a table may be referenced either using a subscript or an index. Syntactically, 
this is coded using parenthesis, as per the following three examples, all of which store the 
letter ‘A’ into the 17th occurrence of a data item named WS-Output-Image-TXT: 


1. MOVE ’A’ TO WS-Output-Image-TXT (17) 
2. MOVE 17 TO WS-OI-SUB 

MOVE ’A’ TO WS-Output-Image-TXT (WS-OI-SUB) 
3. SET WS-OI-IDX TO 17 

MOVE ’A’ TO WS-Output-Image-TXT (WS-OI-IDX) 


The Ist and 2nd examples are referred to as Subscripting while the 3rd is known as 
Indexing. The distinction is fairly simple. 


Indexing is the process of referencing an element of a table utilizing a data item with 
an explicitly or implicitly defined USAGE (see [USAGE], page 232) of INDEX to select the 
desired occurrence, while ... 


Subscripting is the process of referencing an element of a table utilizing either a numeric 
constant or an unedited numeric data item to select the desired occurrence. 


Various implementations of COBOL generate object code that is quite different in each 
of these three situations, and GnuCOBOL is no exception. 


In general, table references such as example #1 (constant subscript) generate the small- 
est, simplest and fastest object code while table references such as example #2 (numeric 
data item subscript) generate the largest, most-complicated and slowest object code. 


Table references such as example #3 (table indexing) generate object code that falls in 
the middle of the other two but is far closer in efficiency to example #1 than #2. 


Some COBOL statements (SEARCH (see [SEARCH], page 377), SEARCH ALL (see 
[SEARCH ALL], page 379) and the table-based SORT (see [Table SORT], page 395)) 
require you to index the affected table and to utilize that index with those statements. 
With any other references to tables, the choice is left to the programmer as to which 
approach should be used. In general, follow these rules: 


1. Use constant subscripts (example #1) wherever possible/practical. 


2. If references to table elements are going to be performed many, many times (tens or 
hundreds of thousands of times or more) during program execution, you will proba- 
bly see a noticeable reduction in program execution time if you use indexing versus 
subscripting. 


It’s impossible to perform any arithmetic operation against an index data item directly 
(other than a simple incrementation or decremental operation via the SET UP/DOWN state- 
ment (see [SET UP/DOWN], page 386)). Situations where any non-trivial computations 
are required to calculate the effective occurrence number for a table reference will require 
you to use a conventional unedited numeric data item as the receiving field for the calcu- 
lation. That calculated value would then need to be saved into the index data item via a 
SET Index statement. 


If you only need to use the computed occurrence number once, you might as well just use 
the computed occurrence number data item as a subscript. If, however, you will need to use 


Chapter 12 - Programming Style Suggestions 15 January 2023 


GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 699 


a computed “subscript” many more times than once, the run-time overhead of converting 
that occurrence value to an index (via SET Index) will be worth the coding effort. 


Whew! 


If references to table elements are not going to be performed many, many times it 
probably won’t make much difference whether you use indexing or subscripting. 


If you are comfortable with the C programming language, you might find the following 
simple GnuCOBOL program useful in exploring the differences between subscripting and 
indexing: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. SUBVSINDEX. 
DATA DIVISION. 

WORKING-STORAGE SECTION. 


01 WS-TABLE-SUB BINARY-LONG. 
01 WS-TABLE. 
05 WS-TABLE-ENTRY OCCURS 20 TIMES 
INDEXED BY WS-TABLE-IDX 
PIC X(1). 


PROCEDURE DIVISION. 
000-Main SECTION. 
E1. MOVE ’A’ TO WS-TABLE-ENTRY (17) 


E2. MOVE 17 TO WS-TABLE-SUB 
MOVE ’A’ TO WS-TABLE-ENTRY (WS-TABLE-SUB) 


E3. SET WS-TABLE-IDX TO 17 
MOVE ’A’ TO WS-TABLE-ENTRY (WS-TABLE-SUB) 


Compile this program as follows (the assumption is made that you are executing the 
cobc command from the directory in which the above program source code (subvsindex.cbl) 
exists. 


cobc -C -save-temps subvsindex.cbl\ 


After this command is executed, the file subvsindex.c will contain the procedure divi- 
sion C code and subvsindex.c.1.h will contain the working-storage C code. Compare the 
generated C code for each of the three MOVE statements. 


12.4. Copybook Naming Conventions and Usage 


Since the intent of a copybook is to introduce COBOL code into a particular spot in a 
program via the COPY statement (see [COPY], page 63), it is always a good idea to prefix 
copybook names with a character sequence that identifies where in a program its contents 
are intended to be COPYed. 


For example: 
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IDXxxxxxxx 
Copybooks containing code intended for the identification division. These will 
be rare as you almost never encounter copied code in the identification division. 


EDxxxxxxxx 
Copybooks containing code intended for use in the environment division. 
These copybooks are generally used for predefined SPECIAL-NAMES (see 
[SPECIAL-NAMES], page 92) or FILE-CONTROL (see [INPUT-OUTPUT 
SECTION], page 103) syntax, 


DDxxxxxxxx 
Copybooks that contain data definitions. 


PDxxxxxxxXx 
Copybooks that contain executable instructions. 


12.5. PROCEDURE DIVISION Sections Versus Paragraphs 


The issue of whether to use section and/or paragraph names (collectively referred to as 
procedure names) within the procedure division is one of near religious significance with 
many COBOL programmers. 
COBOL programming standards used by many organizations that use the language 
generally call for procedure names to: 
1. Contain a leading numeric component (for example: 2000-Update-Customer), 
AND... 


2. Be defined in the procedure division in non-decreasing sequence of that numeric com- 
ponent. 


When you are looking at or editing any large COBOL program that has been created 
with programming standards that include these two rules, it is always a simple thing to 
know whether a reference to a procedure is being made to code that exists before or after 
your current location in the program, simply by comparing the numeric component of the 
current procedure’s name with the one in question. 

Technically, GnuCOBOL does not require ANY procedure names be defined unless: 

1. You are using the ALTER statement (see [ALTER], page 292) (the use of which should 
be avoided at all costs) 
You are using a procedural PERFORM statement (see [Procedural PERFORM], page 360) 
You are using a GO TO statement (see [GO TO], page 335) 
You are using a MERGE statement (see [MERGE], page 349) with an OUTPUT PROCEDURE 


You are using a SORT statement (see [SORT], page 391) with either (or both) an INPUT 
PROCEDURE or OUTPUT PROCEDURE 


6. You are using DECLARATIVES (see [DECLARATIVES], page 254) 


Clie ees 


Since it is difficult to write any non-trivial COBOL program that uses none of the above, 
lets assume you will be including at least one section or paragraph in your GnuCOBOL 
programs. 
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1. 


I like to use procedure division paragraphs and sections as follows: 
The very first procedure defined in the procedure division of my programs, assuming no 
DECLARATIVES (see [DECLARATIVES], page 254) are defined, will be a section named 
000-Main. The declaration of this procedure will immediately follow the procedure 
division header (or END DECLARATIVES if DECLARATIVES are used). 


Any procedures referenced by MERGE, PERFORM, or SORT statements will be defined as 
sections. 

Any procedures referenced by GO TO statements will be defined as paragraphs, and those 
paragraphs will be defined in the same section as the GO TO statements that reference 
them. In other words, GO TO statements may not be used to transfer control to a 
point in a different section. This is not a GnuCOBOL rule — this is my own personal 
programming practice intended to improve the readability and maintainability of my 
programs. 

T always include a numeric prefix to all procedure names I define, for the reasons stated 
earlier. 

I do not use THRU on any MERGE, PERFORM or SORT statement unless the programming 
standards of the shop in which I am working require it. My reasoning for this is that 
it is too easy to accidentally introduce a new procedure into the scope of a THRU. 


12.6. COMPUTE Versus ADD-SUBTRACT-MULTIPLY- 
DIVIDE 


Over the years, there has been much debate over the efficiency and arithmetic accuracy 
of using the COMPUTE statement (see [COMPUTE], page 301) rather than the four basic 
arithmetic operation statements. 


Here are the facts — draw your own conclusions as to which approach is more appropriate 


under which circumstances. 


1. 


15 


The COMPUTE statement supports exponentiation (via the ‘**’ operator) — there is no 
equivalent basic arithmetic statement. Although you could simulate integral exponenti- 
ation (raising a value to the third power, for example) using MULTIPLY statements, and 
you may use the SQRT intrinsic function (see [SQRT], page 511) to find a square root, 
there’s just no (easy) way to find the cube-root of a value without using the COMPUTE 
statement. 
For non-trivial computations, COMPUTE statements “read” better. Take this, for exam- 
ple: 

COMPUTE R = (A +B ¥* C) / D 
As compared to: 

MULTIPLY B BY C GIVING TEMP 

ADD A TO TEMP 

DIVIDE TEMP BY D GIVING R 
For non-trivial computations, COMPUTE statements may execute faster than the equiv- 
alent chain of basic arithmetic statements. For example, the COMPUTE statement 


shown above executes about 25% faster on my computer using GnuCOBOL than does 
the MULTIPLY-ADD-DIVIDE sequence. 
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3. For trivial computations, on the other hand, I prefer the inherent readability of a 
statement such as this: 


ADD 1 TO WSS-Input-Trans-QTY 
to this: 
COMPUTE WS-Input-Trans-QTY = WS-Input-Trans-QTY + 1 


End of Chapter 12 — Programming Style Suggestions 
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13. Programming for XFD 


This chapter deals with the initial support for ODBC and OCI as file-handlers (so far Post- 
erSQL, MySQL, SQLite, MSSQL) and OCI, along with new directory COB_LSCHEMA_DIR 
containing the necessary internal schema files to match the file definition to the database 
table all though usage of $XDF. 


13.1. GnuCobol use SQL for files 


The ACUCOBOL compiler has a defined syntax for describing records that can be stored 
in SQL tables. This is referred to as XFD (extended file descriptor). The various XFD 
directives are intermixed in the record description of a data file as either $XFD (similar to 
$SET) or as comments *((XFD_ )). Each directive precedes the data item it is affecting. 
When a program is compiled that has these directives and the compiler is directed by a 
compile option, then the record layout is written out to a text file which is later used at run- 
time to process the data records. i.e., facilitate mapping the COBOL data fields to/from 
SQL columns. 


The goal of this project is for GnuCOBOL to accept directives similar in syntax to the 
ACUCOBOL XFD syntax1 (plus a few additions as required) and develop run-time modules 
to handle all of the COBOL I/O verbs while the data is stored in a SQL table. 


The purpose for doing this is to allow legacy COBOL to have data stored in SQL tables 
without rewriting the COBOL code. If a COBOL based application is already using EXEC 
SQL this feature of having INDEXED files stored in SQL tables is really not of any use. 
Once the data is in SQL tables it may be accessed by other SQL tools. To get access to 
more advanced SQL features, the COBOL code will need to be recoded to use EXEC SQL, 
but this can be done at points which provide the most advantage. 


At present both INDEXED and RELATIVE files are supported using either an ODBC 
or OCI (Oracle Call Interface) interface. RELATIVE files are supported by adding a special 
column that gets a unique number as the RELATIVE KEY. The intention is that you could 
store the data for the master data files of an application in an SQL database. Often COBOL 
based applications have intermediate data files and it would be a waste of time to place 
these into the database. Also keep in mind that the performance of ISAM will be much 
better than using an SQL database. However, SQL provides the opportunity to use ad hoc 
inquiry and other third party tools to process your data. 

When directed by the XFD directives, the GnuCOBOL compiler will write out the 
CREATE TABLE statements that could be used to represent the file. The GnuCOBOL 
compiler will also write out a data description file which is read at runtime and used to 
manage the conversion of data between the COBOL record view and the SQL column view. 
The format of this data description file is not exactly the same as what ACUCOBOL had 
used since the file is easily regenerated. The more important feature is to accept similar 
XFD directives intermixed in the record description. 


XFD Directives 


The following directives are accepted intermixed in the COBOL record description. The 
KEY IS clauses from SELECT statements will be used to generate SQL INDEX statements. 
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$XFD Name 
ALL 


FILE 


ALPHA 


BINARY 


CHAR 


DATE 


GROUP type 


NAME 
NUMERIC 


USE type 
VARCHAR 


VAR-LENGTH 
WHEN fid op val 


AND fid op val 


OR fid op val 


Name 
-fsqldb=name 
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XFD Directive Descriptions 

Indicates this is a special module defining all files in an application 
system so all files in this module should be defined for use via SQL 
Name to be used for SQL table, filename.ddl and filename.xd instead 
of guessing from the SELECT /ASSIGN. If FILE is not provided then if 
ASSIGN filename is used that is taken, other wise the SELECT name 
is used for the table name and the .ddl and -xd files. 

Next field is handled as a single CHAR type. If a group item the entire 
group is a single CHAR column. May optionally have alternate name. 
Next field handled as BINARY (RAW) so arbitrary hex data is stored. 
If a group item the entire group becomes a single BINARY column. 
May optionally have alternate name 

Next field is handled as a single CHAR type. If a group item the entire 
group is a single CHAR column. May optionally have alternate name. 
Next field is a date in the defined format 

M - month (01 12), Y - year (2 or 4 digit), D - day of month (01-31) 
H - hour (00 -23), N minute, S second, T - hundredths of a second 
J - Julian day, E - day of year 

YY%nn nn is the pivot year 

YYY+nnnn nnnn is added to YYY to compute the actual year 

The next field or group item is taken as a single SQL column of the 
declared type 

Name to be used for the next SQL column 

Next field is handled as NUMERIC, may optionally have alternate 
name 

The word USE is essentially ignore and the next word defines the field 
type 

Emit next field as VARCHAR instead of CHAR 

Emit next field as VARCHAR instead of CHAR 

fld is some previous field in the record, val is a numeric value of alpha 
value in quotes, op is one of =, !=, >, >=, <, <=. val may be other 
to indicate other cases. If the condition is true then the following 
field/group format is used. 


A continuation of the previous WHEN logically connect as an AND 
condition 
A continuation of the previous WHEN logically connect as an OR 
condition 


GnuCOBOL Compile time Option Descriptions 
name indicates which database is to be used. Choose one of ODBC, 
MySQL, MSSQL, OCI, Oracle10, Oraclel1, Oracle12. 
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- name is sub-directory into which the filename.ddl holding CREATE 

fsqlschema=name TABLE is written as well as the filename.xd holding the data mapping 
information. If omitted then the ddl/xd files are written to the base 
schema_dir directory. 


Environment 
Variable runtime.cfg GnuCOBOL Run time Option Descriptions 


COB_SCHEMA_DIR  schema_dir Define location where the filename.xd files are 
stored. Default: $COB_CONFIG_DIR/schema 
COB_SCHEMA_NAME schema_name Database schema name 
COB_SCHEMA_UID schema_uid Database User-id for connecting to the database 
COB_SCHEMA_PWD schema_pwd Password for database User-Id 
COB_SCHEMA_DSN schema_dsn DSN name for database 
COB_DEBUG_LOG Parameters for GnuCOBOL logging feature. 
Module type is db 


Implementation Plan - GnuCOBOL Developer Notes 


To support $XFD directives changes were made to pplex.1, ppparse.y and scanner.|. Also 
codegen.c and field.c will need changes. 


Additional flags may have to be added to cb_field to retain the XFD directive informa- 
tion. 


In codegen.c (output_file_initialization) depending on use of XFD and compile options 
is the location to emit the CREATE TABLE and the data description file. The cob_file will 
get some new flags for io_routine to indicate the file is really handled by ODBC/OCI. 


A new fileio routine (fodbc.c and later foci.c) were developed following the recently devel- 
oped interface for multiple I/O handlers. The cob_load_xfd routine loads the data descrip- 
tion file into internal structures. Multiple schemas could have the same table name/structure 
for development, QA, production, etc. This could be indicated via runtime.cfg options 
and/or environment variables. IO_asgname may have format=odbc or format=oci to in- 
dicate which method is used to access the SQL table for the file. You may also specify 
table=sql_table_name to override the default SQL table. 


At run-time when the file is opened the file description is loaded into memory for fast 
access and conversion of the data between COBOL data type and SQL column data. Since 
SQL tables are usually collected under a database schema well need a compile option to 
generate the external file description under either a default directory or under a given 
schema name. At run-time an environment variable and/or runtime.cfg option could be 
used to define which database schema is to be used along with the database user-id and 
password. Often a database user-id has a default schema associated with it. 


The module fsqlxfd.c contains routines common to both fodbc.c and foci.c such as loading 
of the filename.xd information and conversion of the data between SQL and COBOL data 
types. When the file is OPENed and the table is found to not exist, then cob_load_ddl 
loads the filename.ddl into memory for the OCI/ODBC routine to submit the CREATE 
TABLE/INDEX statements as required. As the table is loaded, if it contains column types 
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not supported by the current database then there is a translation done during the load 


process. 


Format of filename.xd 


GnuCOBOL has its own format instead of using what ACUCOBOL had. The first 
character on each line indicates what the line is. Lines starting with # or * are comments. 
Each field is separated by a comma. 


Name 
H 

1 
table 


Label 


Opcode 
Operand 
Value 


Name 
D 
num 
date 
num 
num 
num 
yy rule 
num 
P:L 
P:L 


Header Line Description 

Is a header 

Version number 

SQL table name 

For character used as decimal, default , 

For character used as comma, default . 
Indicate how numeric signs are handled 

File type, 3 for INDEXED, 2 for RELATIVE 


Label Description 
Is a Label 
Numeric label, may be referenced by goto or condition 


Goto Description 
Is a Goto 
Numeric label to transfer to 


Condition Description 

Is a Condition to be tested (Appear in postfix sequence) Complex WHEN 
clauses become multiple Condition tests 

If condition test is true, then goto this label, 0 indicates more coming, 
non-zero indicates end of the WHEN condition to be tested 

P=, 7, <=, 8, l= bees yd 

Usually the data field 

String in quotes or numeric value 


Date Format Description 

Date format definition 

Unique number for this format 

Date format string 

Total number of digits in this date field 
1 if DATE present else 0 

1 if TIME present else 0 

+ means add yyAdj to YY, % defines pivot point 
Value for adjusting the Year 

Year Position and Length within field 
Month Position and Length within field 
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P:L Day Position and Length within field 

P:L Hours Position and Length within field 

P:L Minutes Position and Length within field 

P:L Seconds Position and Length within field 

P:L Century date Position and Length within field 


You may define how your application stores DATE information. The database will 
always expect dates to be in a full YYYYMMDD format and date/time to be in YYYYM- 
MDDHHMISS format. Date fields could be defined like the following: 


$XFD DATE "YYYYMMDD" 
$XFD DATE "YY%60MMDD" 
$XFD DATE "YYY+1800MMDD" 
$XFD DATE "YYMMDDCC" 


The Y is a place holder for YEAR, MM for month, DD for day, HH hour, MI minutes, 
SS seconds, CC for century. If the Ys are followed by % then the digits after the % defines 
a pivot year used to map the YY value into a 4 digit year. In the above example if the YY 
value is below 60 then it is 19YY else 20YY 

If the Y’s are followed by + then the digits after the + are added to the Y value. In above 
example, the year is 1800 + YYY value. There is a limit of 16 different DATE formats per 
record. 

If the day is defined like DDD (3 Ds) then it is taken to be the day of the year. For 
example: 


$XFD DATE "YYYYDDD" 


Name Data Description 

F Define data Field 

num Offset from record to start of COBOL data field 
num Bytes occupied by COBOL data field 

num Type of data field 


1 Arbitrary Binary Data 

2 PIC S9 COMP-5 

3 PIC 9 COMP-5 

4 PIC 9 COMP-6 

5 PIC S9 BINARY /COMP/COMP-4 

6 PIC 9 BINARY/COMP/COMP-4 

7 PIC x COMP-X 

8 COMP-1/COMP-2 

9 PIC S89 COMP-3/PACKED DECIMAL 
10 PIC 9 COMP-3/PACKED DECIMAL 
11 PIC $9 SIGN LEADING 

12 PIC $9 SIGN LEADING SEPARATE 
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columns 
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13 PIC S9 

14 PIC 9 SIGN TRAILING 

15 PIC 9 SIGN TRAILING SEPARATE 
16 PIC 9 

17 PIC A 

18 PIC X National characters 

19 PIC X Wide characters 

20 PIC X 

21 PIC X - VARCHAR 


Bytes needed to store as SQL data 
Digits in numeric field 

Scale (or decimal places) 

Unique id of date format (see D) 
COBOL level number 

SQL Column name used for data field 


Key Definitions Description 

Define an index 

Index number (1 16) 

Y if duplicates allowed, else N 

Y if key may be suppressed, else N 

Suppress character either as c or OxHH or string 

Comma separate list of column names in order that make up the index 


Example Records to Table With the following: 


SELECT OPTIONAL TSPFILE 

ASSIGN TO "testsql" 

ORGANIZATION INDEXED ACCESS DYNAMIC 
RECORD KEY IS PRIME-KEY 

SOURCE IS CM-CUST-NUM 


ALTERNATE RECORD KEY IS SPLIT-KEY2 
SOURCE IS CM-TELEPHONE,CM-MACHINE WITH DUPLICATES 
SUPPRESS WHEN "900" 


ALTERNATE RECORD KEY IS SPLIT-KEY3 

SOURCE IS CM-DISK,CM-DP-MGR,CM-MACHINE WITH DUPLICATES 
SUPPRESS WHEN ALL "x" 

FILE STATUS IS CUST-STAT 


SELECT FLATFILE ASSIGN "relfile" 
ORGANIZATION RELATIVE 
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ACCESS IS RANDOM RELATIVE KEY IS REC-NUM 
FILE STATUS IS CUST-STAT. 


SELECT FLATSEQ ASSIGN "relfile" 

ORGANIZATION RELATIVE 

ACCESS IS SEQUENTIAL RELATIVE KEY IS REC-NUM 
FILE STATUS IS CUST-STAT. 


Note that FLATFILE and FLATSEQ are the same file called relfile with a different 
ACCESS. Given the following record description: 


$XFD ALL 
FD FLATFILE 
BLOCK CONTAINS 5 RECORDS. 


01 FLAT-RECORD. 


10 RL-CUST-NUM PICTURE X(8). 

10 RL-COMPANY PICTURE X(25). 

10 RL-TRAILER PICTURE X(16). 
FD FLATSEQ 


BLOCK CONTAINS 5 RECORDS. 


01 RS-RECORD. 


10 RS-CUST-NUM PICTURE X(8). 

10 RS-COMPANY PICTURE X(25). 

10 RS-TRAILER PICTURE X(16). 
FD TSPFILE 


BLOCK CONTAINS 5 RECORDS. 


$XFD NAME=tspfilex 
01 TSPFL-RECORD. 
05 TSPFL-REC. 
$XFD USE GROUP CUSTNUM 
10 CM-CUST-NUM. 


15 CM-CUST-PRE PICTURE X(3). 
15 CM-CUST-NNN PICTURE X(5). 
10 CM-STATUS PICTURE X. 
10 CM-COMPANY PICTURE X(25). 


$XFD USE GROUP VAR_LENGTH custaddr 
10 CM-ADDRESS. 
15 CM-ADDRESS-1 PICTURE X(25). 
15 CM-ADDRESS-2 PICTURE X(25). 
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15 CM-ADDRESS-3 PICTURE X(25). 
10 CM-TELEPHONE PICTURE 9(10). 
10 CM-DP-MGR PICTURE X(25). 
10 CM-MACHINE PICTURE X(8). 
10 CM-MEMORY PICTURE X(4). 
$XFD WHEN (CM-STATUS = ’A’ && CM-TELEPHONE > 100) 
$XFD AND CM-MACHINE = ’B’ || CM-COMPANY = ’ ’ 
10 CM-MEMORYX REDEFINES CM-MEMORY. 
15 CM-MEMSZ PICTURE 9(2). 
15 CM-MEMUNIT PICTURE X(2). 
10 CM-DISK PICTURE X(8). 
10 CM-TAPE PICTURE X(8). 
$XFD WHEN CM-STATUS = ’X? 
10 CM-TAPEX REDEFINES CM-TAPE PICTURE 9(8). 
$XFD WHEN CM-STATUS = ’Y’ 
10 CM-TAPEY REDEFINES CM-TAPE PICTURE 9(6)V99. 
10 CM-NO-TERMINALS PICTURE 9(5) BINARY. 
10 CM-COMPX PICTURE XXX COMP-X. 
10 CM-COMP5 PICTURE 9(7) COMP-5. 
10 CM-COMP1 COMP-1. 
10 CM-COMP2 COMP-2. 
10 CM-PRICE PICTURE 9(3)V99 COMP-3. 
10 CM-PRICES PICTURE S9(5)V99. 
$XFD DATE "MMDDYYYY" 
10 CM-DATE PICTURE 9(8) COMP-3. 
$XFD DATE "YYMMDDCC" 
10 CM-DATE2 PICTURE 9(8) COMP-3. 


And the resulting SQL table(s) would look like: 
tspfilex.ddl -- 


CREATE TABLE tspfilex ( 


custnum CHAR(8) NOT NULL, 
status CHAR(1), 

company CHAR(25) , 

custaddr VARCHAR(75) , 
telephone DECIMAL(10) NOT NULL, 
dp_mgr CHAR(25) NOT NULL, 
machine CHAR(8) NOT NULL, 
memory CHAR(4) , 

memsz DECIMAL (2) , 
memunit CHAR(2) , 

disk CHAR(8) NOT NULL, 
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tape CHAR(8) , 
tapex DECIMAL (8) , 
tapey DECIMAL(8,2), 
no_terminals DECIMAL(5) , 
compx DECIMAL(8) , 
comp5 DECIMAL (7) , 
comp1 FLOAT (23) , 
comp2 FLOAT (53) , 
price DECIMAL(5,2), 
prices DECIMAL(7,2), 
date_x DATE, 

date2 DATE 


)3 

CREATE UNIQUE INDEX pk_tspfilex ON tspfilex (custnum) ; 
CREATE INDEX ki_tspfilex ON tspfilex (telephone ,machine) ; 
CREATE INDEX k2_tspfilex ON tspfilex (disk,dp_mgr,machine) ; 


relfile.ddl -- 


CREATE TABLE relfile ( 


cust_num CHAR(8) , 
company CHAR(25) , 
trailer CHAR(16) , 
rid_relfile BIGINT PRIMARY KEY 


The tspfilex.xd description for this follows: 


, tspfilex,2, 7 5053 
>MMDDYYYY’? , 8. 1,0,,0,4:4,0:2,2:2, 
>? YYMMDDCC’ ,8,1,0,,0,0:2,2:2,4:2, 
000 ,0008,20,0009,0,0, ,10, custnum 
008 ,0001,20,0002,0,0, ,10,status 
009 ,0025,20,0026,0,0, ,10, company 
034,0075,21,0076,0,0, ,10, custaddr 
09,0010,16,0013,10,0,,10,telephone 
19,0025,20,0026,0,0,,10,dp_mgr 
44 ,0008,20,0009,0,0,,10,machine 
,=,Status,’A’ 
>> epee 100 


0,0 


0, 
0,0:0 


O: :0,0:0,0:0 
O: :0,0:0,6:2 


1 
1 


> 
: 


> > 


5 Dine >B? 


> 


> 


H,1 
D,1, 
D,2 
F,0 
F,0 
F,0 
F,0 
F,0 
F,0 
F,O1 
C,0 
C,0 
C,0,& 
C,0 
C,0 
C,0 


,=,company,’ ’ 


> 2 
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152 ,0004,20,0005,0,0, ,10,memory 


. 


152,0002,16,0005,2,0, ,15,memsz 
154,0002,20,0003,0,0, ,15,memunit 


156,0008,20,0009,0,0,,10,disk 
,=,Status,’X’ 
=,status,’Y’ 
64,0008, 20,0009,0,0,,10,tape 


parc 


. 


210,0005,10,0032,8,0,2,10,date2 
»N,N,,custnum 
»Y,Y,"900",telephone ,machine 
»Y,Y,0x2A,disk,dp_mgr,machine 


AAR DDDA ara ye AP aAaArraAnTaAaArAHrATA 


The relfile.xd description for this follows: 


H,1,relfile,0,’,’,’.’,0,2 
F,0000,0008,20,0009,0,0, ,10, cust_num 
F,0008 ,0025,20,0026,0,0,,10, company 
F,0033,0016,20,0017,0,0, ,10,trailer 
F,0049,0004,03,0015,12,0,,00,rid_relfile 
K,0O,N,N,,rid_relfile 


Application Schema 


Sometimes COBOL programs will have local views of the data by copying a record to 
some other group item which redefines the data differently. In some cases these hidden 
redefines will cause problems for SQL columns. For example, if a field is defined as PIC 
9(x) but sometimes the same location in the record contains non-numeric data, then SQL 
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will reject the storing of such data as it violates the strict data typing. By using the $XFD 
WHEN you are able to define which a portion of the record has one view other another. 
The I/O logic will then only copy the valid column of data. 


It may therefore be a good idea to collect all of the file definitions into a single module, 
verify that all possible redefines are identified. The $XFD ALL directives indicates that 
such a module is being compiled. Think of this module as defining all of the master data 
files in an application which will be migrated into SQL tables. 


Check the DDL 


It is a good idea to check the DDL generated by the GnuCOBOL compiler and make 
sure it suits your local database guidelines. You may also need to add local directives such 
as a STORAGE clause for Oracle. You should then use the appropriate tool (eg. Mysql 
or sqlplus) and manually create all of the tables to be used by an application. There may 
also be considerations for what database user-id has permission to create tables, read/write 
tables etc. 


Automatic Table Creation 
At OPEN time, the filename.xd is processed and if not present that is considered a 
serious error (30) is returned. 


At OPEN time, a check is done to see if the table exists and if not, the run-time code 
then reads the filename.ddl and submits it to the database to create the table and indexes. 
If the filename.ddl is not present then OPEN is given an error (30). If runtime.cfg op- 
tion create_table is true then the runtime will attempt to recreate filename.ddl from the 
information in filename.xd. 


Taken from Development Notes by Ron Norman February 2020. 


End of Chapter 13 — Programming for XFD 
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Appendix A - Glossary of Terms 


Alphabetic Data Item 
A data item whose PICTURE clause allows it to contain only upper- and/or 
lower-case letters. See [PICTURE], page 194. 


Alphanumeric Data Item 
A data item whose PICTURE clause allows it to contain absolutely any character 
whatsoever. See [PICTURE], page 194. Group items (see [Structured Data], 
page 14) are also implicitly considered to be alphanumeric data items. 


Alphanumeric Literal 
A string of characters enclosed within a pair of quotation marks (‘"’) or apos- 
trophes (‘’’). See [Alphanumeric Literals], page 35. 


Called Program 
Another way to refer to a subprogram. Note that a called program may also 
be a calling program. 


Calling Program 
A program that executes a subprogram. Note that a calling program may also 
be a called program. 


Collating Sequence 
The sequence in which the characters that are acceptable to a computer are 
ordered for purposes of all types of sorting, merging, comparing, and processing. 
GnuCOBOL programs may utilize standard character-set collating sequences 
(such as that defined by the ASCII or EBCDIC character sets) or programmer- 
defined custom sequences as specified in the OBJECT-COMPUTER paragraph 
(section 4.1.2) and defined in the SPECIAL-NAMES paragraph (section 4.1.4). 


Compilation Group 
The collection of all compilation units being compiled by a single execution of 
the GnuCOBOL compiler. 


Compilation Unit 
A single source file being compiled by the GnuCOBOL compiler. A compilation 
unit may contain one or more programs. 


Control Break 
An event that is triggered when a control field on an RWCS-generated report 
changes value. It is these events that trigger the generation of control heading 
and control footing groups. 


Control Field 
A field of data being presented within a detail group; as the various detail 
groups that comprise the report are presented, they are presumed to appear 
in sorted sequence of the control fields contained within them. As an example, 
a department-by-department sales report for a chain of stores would probably 
be sorted by store number and — within like store numbers — be further sorted 
by department number. The store number will undoubtedly serve as a control 
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field for the report, allowing control heading groups to be presented before each 
sequence of detail groups for the same store and control footing groups to be 
presented after each such sequence. 


Control Footing 

A report group that appears immediately after one or more detail groups of 
an RWCS-generated report. Such are produced automatically as a result of a 
control break. This type of group typically serves as a summary of the detail 
group(s) that precede it, as might be the case on a sales report for a chain 
of stores, where the detail groups documenting sales for each department (one 
department per detail group) from the same store might be followed by a control 
footing that provides a summation of the department-by-department sales for 
that store. 


Control Heading 

A report group that appears immediately before one or more detail groups 
of an RWCS-generated report. Such are produced automatically as a result 
of a control break. This type of group typically serves as an introduction to 
the detail group(s) that follow, as might be the case on a sales report for a 
chain of stores, where the detail groups documenting sales for each department 
(one department per detail group) from the same store might be preceded by a 
control heading that states the full name and location of the store. 


Control Hierarchy 
The natural hierarchy of control breaks within a RWCS-controlled report based 
upon the manner in which the data the report is being generated from is sorted. 


Copybook 
A segment of program code that may be utilized by multiple programs sim- 
ply by having that program use the COPY statement to import that code into 
the program. Although similar to the “include” facility present in many other 
programming languages, the COBOL copybook mechanism is actually consid- 
erably more powerful. See [Copybooks], page 14, for a general discussion. See 
[COPY], page 63, for the specifics of the COPY statement. 


Data Item 
A contiguous area of storage within the memory space of a program that may 
be referenced, by name, in a COBOL program. Other programming languages 
use the term variable, property or attribute to describe the same concept. See 
[Structured Data], page 14. 


Detail Group 
A report group that contains the detailed data being presented for the report. 


Detail Report 
An RWCS%-generated report to which at least one type of detail group is pre- 
sented. 


Division A collection of zero, one, or more sections of paragraphs, called the division 
body, that are formed and combined in accordance with a specific set of rules. 
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Each division consists of the division header and the related division body. 
There are four divisions in a GnuCOBOL program: Identification, Environ- 
ment, Data, and Procedure (coded in that sequence). See [Program Structure], 
page 31. 


Dynamic Subprogram 
A subprogram whose executable object code is contained in a different exe- 
cutable file as its calling program. Dynamic subprograms are therefore loaded 
into memory as needed. 


Elementary Item 
A data item that isn’t itself comprised of other data items. See [Structured 
Data], page 14. 


Entry-point 
A spot in the procedure division where a program may begin execution when 
it is executed from the operating system, invoked as a user-defined function or 
called by another program. 


Every program has at least one entry-point — known as the primary entry- 
point — which corresponds to the first executable statement in the procedure 
division following the declaratives area, if any. 


Additional entry-points may be defined via the ENTRY statement (see [ENTRY], 
page 318). 


Entry-point Name 
Every entry-point has a name. That name must be unique for all programs 
that comprise an executable program. Entry-point names are defined using 
a subroutine’s PROGRAM-ID paragraph, a user-defined function’s FUNCTION-ID 
paragraph or via ENTRY (see [ENTRY], page 318) statements coded in a sub- 
program’s procedure division. 


Executable File 
The GnuCOBOL compiler can create operating-system appropriate files that 
may be executed directly from the operating system environment. On Windows 
systems, these will be .exe files whereas on UNIX systems they will have no 
specific extensions. The compiler’s -x switch is used to create executable files. 
Only main programs should be compiled in this manner. 


Execution Thread 
The complete set of executable code that is run during the execution of a 
program. This includes the main program as well as all executed subprograms, 
including those that are both dynamically and statically loaded. 


Figurative Constants 
GnuCOBOL, like other COBOL implementations, supports a number of re- 
served words that may be used to represent a specific literal value. These are 
known as figurative constants. See [Figurative Constants], page 36, for more 
information. 
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Fixed Format Mode 


A mode of the GnuCOBOL compiler’s operation where source statements are 
constrained to meeting the pre-2002 standard of limiting COBOL statements 
to 80 columns, with various columns having limitations as to what sort of 
COBOL syntax could be specified in them. See [Format of Program Source 
Lines], page 28, for more information. 


Free Format Mode 


Group Item 


A mode of the GnuCOBOL compiler’s operation where source statements are 
allowed to be as long as 255 characters, with no restrictions or requirements 
as to in which columns various syntax elements must appear. See [Format of 
Program Source Lines], page 28, for more information. 


A hierarchical data structure where the group item — itself a data item — 
actually consists of two or more other contiguously allocated data items. For 
example, Employee-Name could be a 35-character data item consisting of a 20- 
character Last-Name data item followed by a 14-character First-Name and a 
1-character Middle-Initial. See [Structured Data], page 14. 


Hexadecimal Alphanumeric Literal 


These are alphanumeric literals whose character sequence is specified by hex- 
adecimal value. These literals are formed by a quote- or apostrophe-delimited 
sequence of an even number of hexadecimal digits (upper- or lower-case), pre- 
fixed with the letter ‘xX’ (also upper- or lower-case). For example, the charac- 
ter string “Demo” could be specified as the hexadecimal alphanumeric literal 
X’44656D6F’, assuming the ASCII character set. See [Alphanumeric Literals], 
page 35. 


Hexadecimal Numeric Literal 


Identifiers 


A numeric literal whose value is specified by hexadecimal value. These lit- 
erals are formed by a quote- or apostrophe-delimited sequence of from 1 to 
16 hexadecimal digits (upper- or lower-case), prefixed with the letter ‘H’ (also 
upper- or lower-case). For example, the number 123456 could be specified as 
the hexadecimal numeric literal H’?01E240’. See [Numeric Literals], page 34. 


These are data items a COBOL program will be working with. The vast ma- 
jority of identifiers are defined by the user (programmer) while a few are pre- 
defined by the GnuCOBOL compiler. Identifiers pre-defined by the compiler 
are referred to as special registers. Other programming languages generally 
refer to identifiers as “variables”. 


Imperative Statement 


Either a statement that begins with a non decision-making verb and specifies an 
unconditional action to be taken or a conditional verb such as IF or EVALUATE, 
delimited by its explicit scope terminator (such as END-IF or END-EVALUATE). 
An imperative statement can consist of a sequence of imperative statements. 
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Intrinsic Function 


A built-in routine that accepts arguments and returns a value; syntactically, 
these may be used most places where GnuCOBOL identifiers are valid. See 
[Intrinsic Functions], page 421, for documentation on all the GnuCOBOL in- 
trinsic functions. 


Level Number 


Literal 


A 1- or 2-digit number that indicates the hierarchical position of a data item 
in a group item or the special properties of a data description entry. 


Level numbers in the range 1 through 49 indicate the position of a data item 
in the hierarchical structure of a logical record. Level numbers in the range 1 
through 9 can be written either as a single digit or as a zero followed by the 
significant digit. 

Level numbers 66, 77, 78 and 88 identify special properties of a data description 
entry. 


A generic term used for a constant value coded in a program that may be either 
a numeric literal or an alphanumeric literal. 


Main program 


A program that is executed directly from an operating system or shell event. 
Main programs are not executed from other programs (i.e. they are not called 
programs). 


National Character set 


A character set that supports symbols using other than the traditional Roman 
alphabet symbols used by the ASCII character set. Typically, such a character 
set uses a UTF-16 (i.e. 16 bits-per-character) encoding of the Unicode character 
set. 


Support for national character sets in GnuCOBOL is currently only partially 
implemented, and the compile- and run-time effect of using the N symbol in 
a PICTURE (see [PICTURE], page 194) clause to define a field as containing 
national characters is the same as if X(2) had been coded, with the additional 
effect that such a field will qualify as a NATIONAL or NATIONAL-EDITED field on 
an INITIALIZE (see [INITIALIZE], page 339) statement. 


Numeric Data Item 


A data item whose PICTURE clause allows it to contain only the numeric digit 
characters 0-9 (signed or unsigned), or a data item whose PICTURE/USAGE 
combination allow it to contain actual binary numbers in integer, fixed-point, 
floating-point or packed-decimal format. Numeric data items are the only ones 
that may be used as table subscripts or as source arguments on arithmetic 
statements. PICTURE (see [PICTURE], page 194), or USAGE (see [USAGE], 
page 232). 


Numeric Edited Data Item 


An otherwise numeric data item whose PICTURE (see [PICTURE], page 194) 
clause also contains any of the editing symbols ‘$’, ‘*’, ‘+’, ‘,’, ‘-’, £.’, ‘7’, ‘0’ 
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(zero), ‘B’, ‘CR’, ‘DB’ or ‘Z’. Numeric edited data items are not eligible to serve 
as table subscripts or source arguments on arithmetic statements. 


Numeric Literal 
A numeric constant. See [Numeric Literals], page 34. 


Page Footing 
A report group that appears at the bottom of every page of an RWCS-generated 
report. Information typically found within such a report group might be: 


e The date the report was generated 


e The current page number of the report 


Page Heading 
A report group that appears at the top of every page of an RWCS-generated 
report. Information typically found within such a report group might be: 


e A title for the report 
e The date the report was generated 
e The current page number of the report 


e Column headings describing the fields within the detail group(s) 


Primary Entry-Point 
See entry-point. 


Procedure 
All executable code statements within a single procedure division paragraph or 
section. 


Procedure name 
A programmer-defined section or paragraph name in the procedure division as- 
signed to a procedure. Procedure names serve as a means by which a statement 
may refer to the statements that follow the procedure name. 


Program A GnuCOBOL main program or subprogram. 


Qualification 
The process of establishing a unique reference to a data item whose name is 
duplicated in a program. This takes the form of using the duplicated data name 
and the name of any of its parent data items, connected by OF or IN such that 
the combination of those two data names is unique within the program. 


Record A group item that is not part of a higher-level group item. See [Data Definition 
Principles], page 120. An elementary item with a level number of 01 can also be 
referred to as a record if its definition occurs in the file section, provided that 
its definition does not include the CONSTANT attribute. See [FILE-SECTION- 
Data-Item], page 127. 


Report Footing 
A report group that occurs only once in an RWCS-generated report — as the 
very last presented report group of the report. These typically serve as a visual 
indication that the report is finished. 
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Report Group 
One or more consecutive lines on a report that serve a common informational 
purpose or function. For example, lines of text that are displayed at the top or 
bottom of every printed page of a report. 


Report Heading 
A report group that occurs only once in an RWCS-generated report — as the 
very first presented report group of the report. These typically serve as an 
introduction to the report. 


Reserved Word 
A word coded in a GnuCOBOL program without any quote or apostrophe 
characters around it (which would have transformed that sequence of characters 
into a literal string) which has a very specific meaning to the compiler. See 
[Language Reserved Words], page 9, for a general discussion of the concept. 
Appendix C for a complete list of GnuCOBOL reserved words. 


Sentence An arbitrarily long sequence of statements terminated by a period. 


Special Registers 
Special data items that are automatically defined for your use by the Gnu- 
COBOL compiler. See [Special Registers], page 265, for a complete list. 


Statement 
A single executable COBOL instruction. All statements start with a verb 
(DISPLAY, IF, MOVE, ...) which is followed by the operands and additional 
syntax elements that describe the actions to be performed. 


Static Subprogram 
A subprogram whose executable object code is part of the same executable file 
as its calling program. Static subprograms are therefore loaded into memory 
at the same time as their caller. 


Subprogram 
A program invoked directly by another program in such a manner that it may 
return control back to the other program, directly back to the point where the 
subprogram was invoked. 


Subroutine 
A subprogram executed from another via a GnuCOBOL CALL (see [CALL], 
page 293) statement (or the equivalent in whatever programming language that 
other program was written in). 


Summary Report 
An RWCS-generated report to which no detail groups are presented. 


User-Defined Function 
A subprogram written in GnuCOBOL that is executed in a syntactically-similar 
manner to that by which the various built-in intrinsic functions are executed. 


User-Defined Names 
Either the name of an identifier or a procedure in the program. GnuCOBOL 
limits user-defined names to a maximum of 31 characters taken from the set 
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of numeric digits, upper- and lower-case letters, hyphens and underscores. A 
user-defined name may neither begin nor end with a hyphen or underscore. 
User-defined names used as file names may additionally not begin with a digit 
although - unlike many other programming languages - user-defined names used 
as identifiers or procedure names may. 


Verb The first reserved word of a COBOL statement. 


Zero-Delimited Alphanumeric Literals 

An alphanumeric literal prefixed with an upper- or lower-case ‘Z’ character — 
for example, Z’ABC’. These literals are one character longer than the value 
within apostrophes or quotes would make them appear. The extra character 
(the last character) will be a null character (comprised entirely of zero bits). 
These literals are ideal when defining or assigning values to alphanumeric data 
items that will be passed as arguments to a C subroutine. See [Alphanumeric 
Literals], page 35. 


End of Appendix A — Glossary of Terms 
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Appendix B - Reserved Word Lists 


See Appendix C for the complete lists of ALL reserved words of all types. 


End of Appendix B — Reserved Word Lists 
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Appendix C1 - Grouped Word Lists by feature 
and function 


The following is the complete list of ALL reserved words in the 15 January 2023 at 16:30 
GMT. build of GnuCOBOL 3.2. Even though the functionality behind some of these words 
may not be implemented in this version of GnuCOBOL, none may be used as any user- 
defined name. This list includes ALL reserved, intrinsics, mnemonics and system and shows 
some 1100+ words in total. In addition there are the arithmetic and relational symbols see 
1.3.15 as well as extra words that can be added and existing words removed by the use of 
the —std file content see the specific one used for each sub-set. 


The following list of reserved words was extracted from cobc --list-reserved and 
shows the reserved words, an implementation 

Please notice: This list is highly specific to the option -std=dialect and reserved word 
options (-freserved=word, -fno-reserved=word) in effect. You can get the list for a given 
dialect by calling cobc -std=dialect --list-reserved. 


Common reserved words 


Reserved word Implemented Aliases 
3-D Yes (C/S) 
ABSENT Yes 
ACCEPT Yes 
ACCESS Yes 
ACTION Yes (C/S) 
ACTIVATING No (G/S) 
ACTIVE-CLASS No 
ACTIVE-X Yes (C/S) 
ACTUAL Yes (C/S) 
ADD Yes 
ADDRESS Yes 
ADJUSTABLE-COLUMNS Yes (C/S) 
ADVANCING Yes 
AFTER Yes 
ALIGNED No 
ALIGNMENT Yes (C/S) 
ALL Yes 
ALLOCATE Yes 
ALLOWING Yes (C/S) 
ALPHABET Yes 
ALPHABETIC Yes 
ALPHABETIC-LOWER Yes 
ALPHABETIC-UPPER Yes 
ALPHANUMERIC Yes 
ALPHANUMERIC-EDITED Yes 

ALSO Yes 
ALTER Yes 
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ALTERNATE 

AND 

ANUM 

ANY 

ANYCASE 

APPLY 

ARE 

AREA 

AREAS 
ARGUMENT-NUMBER 
ARGUMENT-VALUE 
ARITHMETIC 

AS 

ASCENDING 

ASCII 

ASSIGN 

AT 

ATTRIBUTE 
ATTRIBUTES 
AUTHOR 

AUTO 
AUTO-DECIMAL 
AUTO-SKIP 
AUTO-SPIN 
AUTOMATIC 
AUTOTERMINATE 
AWAY-FROM-ZERO 
B-AND 

B-NOT 

B-OR 

B-SHIFT-L 
B-SHIFT-LC 
B-SHIFT-R 
B-SHIFT-RC 
B-XOR 
BACKGROUND-COLOR 
BACKGROUND-COLOUR 
BACKGROUND-HIGH 
BACKGROUND-LOW 
BACKGROUND-STANDARD 
BACKWARD 

BAR 

BASED 

BEEP 

BEFORE 

BELL 


Yes (C/S) 


Yes (C/S) 


Yes (C/S) 


(C/S) 


AREAS 
AREA 


AUTO-SKIP, AUTOTERMINATE 


AUTO, AUTOTERMINATE 


AUTO, AUTO-SKIP 


BACKGROUND-COLOUR 
BACKGROUND-COLOR 


BELL 


BEEP 
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BINARY 

BINARY-C-LONG 
BINARY-CHAR 
BINARY-DOUBLE 

BINARY-INT 

BINARY-LONG 
BINARY-LONG-LONG 
BINARY-SEQUENTIAL 
BINARY-SHORT 

BIT 

BITMAP 

BITMAP-END 

BITMAP-HANDLE 
BITMAP-NUMBER 
BITMAP-START 
BITMAP-TIMER 
BITMAP-TRAILING 
BITMAP-TRANSPARENT-COLOR 
BITMAP-WIDTH 

BLANK 
BLINK 

BLOCK 

BOOLEAN 
BOTTOM 

BOX 

BOXED 
BULK-ADDITION 
BUSY 

BUTTONS 

BY 
BYTE-LENGTH 

C 
CALENDAR-FONT 
CALL 

CANCEL 
CANCEL-BUTTON 
CAPACITY 
CARD-PUNCH 
CARD-READER 
CASSETTE 

CCOL 

CD 

CELL 
CELL-COLOR 
CELL-DATA 
CELL-FONT 


15 January 2023 


Yes (C/S) 


Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 


BINARY-LONG-LONG 


BINARY-LONG 
BINARY-INT 
BINARY-DOUBLE 


CELLS 
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CELL-PROTECTION Yes (C/S) 

CELLS Yes CELL 
CENTER Yes (C/S) 

CENTERED Yes (C/S) 
CENTERED-HEADINGS Yes (C/S) 

CENTURY-DATE Yes (C/S) 

CF Yes 

CH Yes 

CHAIN No 

CHAINING Yes 

CHANGED Yes (C/S) 

CHARACTER Yes 

CHARACTERS Yes 

CHECK-BOX Yes (C/S) 

CLASS Yes 

CLASS-ID No 

CLASSIFICATION Yes (C/S) 
CLEAR-SELECTION Yes (C/S) 

CLINE Yes (C/S) 

CLINES Yes (C/S) 

CLOSE Yes 

COBOL Yes (C/S) 

CODE Yes 

CODE-SET Yes 

COL Yes 

COLLATING Yes 

COLOR Yes 

COLORS Yes (C/S) COLOURS 
COLOURS Yes COLORS 
COLS Yes 

COLUMN Yes 

COLUMN-COLOR Yes (C/S) 
COLUMN-DIVIDERS Yes (C/S) 

COLUMN-FONT Yes (C/S) 
COLUMN-HEADINGS Yes (C/S) 
COLUMN-PROTECTION Yes (C/S) 

COLUMNS Yes 

COMBO-BOX Yes (C/S) 

COMMA Yes 

COMMAND-LINE Yes 

COMMIT Yes 

COMMON Yes 

COMMUNICATION Yes 

COMP Yes COMPUTATIONAL 
COMP-O Yes COMPUTATIONAL-O 
COMP-1 Yes COMPUTATIONAL-1 
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COMP-10 Yes COMP-10, DOUBLE, FLOAT-LONG 
COMP-15 Yes COMP-15, DOUBLE, FLOAT-LONG 
COMP-2 Yes COMPUTATIONAL-2 
COMP-3 Yes COMPUTATIONAL-3 
COMP-4 Yes COMPUTATIONAL-4 
COMP-5 Yes COMPUTATIONAL-5 
COMP-6 Yes COMPUTATIONAL-6 
COMP-9 Yes FLOAT, FLOAT-SHORT 
COMP-N Yes COMPUTATIONAL-N 
COMP-X Yes COMPUTATIONAL-X 
COMPUTATIONAL Yes COMP 
COMPUTATIONAL-O Yes COMP-O 
COMPUTATIONAL-1 Yes COMP-1 
COMPUTATIONAL-2 Yes COMP-2 
COMPUTATIONAL-3 Yes COMP-3 
COMPUTATIONAL-4 Yes COMP-4 
COMPUTATIONAL-5 Yes COMP-5 
COMPUTATIONAL-6 Yes COMP-6 
COMPUTATIONAL-N Yes COMP-N 
COMPUTATIONAL-X Yes COMP-X 

COMPUTE Yes 

CONDITION Yes 

CONFIGURATION Yes 

CONSTANT Yes 

CONTAINS Yes 

CONTENT Yes 

CONTINUE Yes 

CONTROL Yes 

CONTROLS Yes 

CONVERSION Yes (C/S) 

CONVERTING Yes 

COPY Yes 

COPY-SELECTION Yes (C/S) 

CORE- INDEX Yes (C/S) 

CORR Yes CORRESPONDING 
CORRESPONDING Yes CORR 

COUNT Yes 

CRT Yes 

CRT-UNDER Yes 

CSIZE Yes (C/S) 

CURRENCY Yes 

CURRENT No 

CURSOR Yes 

CURSOR-COL Yes (C/S) 

CURSOR-COLOR Yes (C/S) 

CURSOR-FRAME-WIDTH Yes (C/S) 


15 January 2023 Appendix C1 - Grouped Word Lists by feature and function 


730 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 
CURSOR-ROW Yes (C/S) 
CURSOR-X Yes (C/S) 
CURSOR-Y Yes (C/S) 
CUSTOM-PRINT-TEMPLATE Yes (C/S) 
CYCLE Yes (C/S) 
CYL-INDEX Yes (C/S) 
CYL-OVERFLOW Yes (C/S) 
DASHED Yes (C/S) 
DATA Yes 
DATA-COLUMNS Yes (C/S) 
DATA-POINTER No 
DATA-TYPES Yes (C/S) 
DATE Yes 
DATE-COMPILED Yes (C/S) 
DATE-ENTRY Yes (C/S) 
DATE-MODIFIED Yes (C/S) 
DATE-WRITTEN Yes (C/S) 
DAY Yes 
DAY-OF-WEEK Yes 

DE Yes 
DEBUGGING Yes 
DECIMAL-POINT Yes 
DECLARATIVES Yes 
DEFAULT Yes 
DEFAULT-BUTTON Yes (C/S) 
DEFAULT-FONT Yes 
DELETE Yes 
DELIMITED Yes 
DELIMITER Yes 
DEPENDING Yes 
DESCENDING Yes 
DESTINATION Yes 
DESTROY Yes 
DETAIL Yes 
DISABLE Yes 

DISC Yes (C/S) 
DISK Yes (C/S) 
DISP Yes (C/S) 
DISPLAY Yes 
DISPLAY-COLUMNS Yes (C/S) 
DISPLAY-FORMAT Yes (C/S) 
DIVIDE Yes 
DIVIDER-COLOR Yes (C/S) 
DIVIDERS Yes (C/S) 
DIVISION Yes 
DOTDASH Yes (C/S) 
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DOTTED 
DOUBLE 
DOWN 
DRAG-COLOR 
DROP-DOWN 
DROP-LIST 
DUPLICATES 
DYNAMIC 
EBCDIC 

EC 

ECHO 
EDITING 
EGI 
ELEMENT 
ELSE 

EMI 
EMPTY-CHECK 
ENABLE 
ENCODING 
ENCRYPTION 
END 
END-ACCEPT 
END-ADD 
END-CALL 
END-CHAIN 
END-COLOR 
END-COMPUTE 
END-DELETE 
END-DISPLAY 
END-DIVIDE 
END-EVALUATE 
END-IF 

END- JSON 
END-MODIFY 
END-MULTIPLY 
END-OF-PAGE 
END-PERFORM 
END-READ 
END-RECEIVE 
END-RETURN 
END-REWRITE 
END-SEARCH 
END-SEND 
END-START 
END-STRING 
END-SUBTRACT 
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Yes (C/S) 

Yes FLOAT-LONG 
Yes 

Yes (C/S) 

Yes (C/S) 

Yes (C/S) 


Yes (C/S) 


Yes (C/S) 


Yes REQUIRED 


Yes (C/S) 


Yes (C/S) 


Yes EOP 
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END-UNSTRING 
END-WRITE 
END-XML 
ENGRAVED 
ENSURE-VISIBLE 
ENTRY 
ENTRY-CONVENTION 
ENTRY-FIELD 
ENTRY-REASON 
ENVIRONMENT 
ENVIRONMENT-NAME 
ENVIRONMENT-VALUE 
EO 

EOL 

EOP 

EOS 

EQUAL 

EQUALS 

ERASE 

ERROR 

ESCAPE 
ESCAPE-BUTTON 
ESI 

EVALUATE 

EVENT 
EVENT-LIST 
EVERY 

EXCEPTION 
EXCEPTION-OBJECT 
EXCEPTION-VALUE 
EXCLUSIVE 
EXCLUSIVE-OR 
EXHIBIT 

EXIT 

EXPAND 

EXPANDS 

EXTEND 
EXTENDED-SEARCH 
EXTERN 

EXTERNAL 
EXTERNAL-FORM 

F 

FACTORY 

FALSE 

FD 

FH--FCD 


Yes (C/S) 
Yes (C/S) 
Yes 

Yes (C/S) 
Yes (C/S) 
Yes (C/S) 


Yes (C/S) 
No (C/S) 
Yes 
Yes (C/S) 
Yes (C/S) 
Yes 
Yes 
Yes (C/S) 
No 


Yes (C/S) 


END-OF-PAGE 


EQUALS 
EQUAL 
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FH--KEYDEF Yes (C/S) 

FILE Yes 

FILE-CONTROL Yes 

FILE-ID Yes 

FILE-LIMIT Yes (C/S) 

FILE-LIMITS Yes (C/S) 

FILE-NAME Yes (C/S) 

FILE-POS Yes (C/S) 

FILL-COLOR Yes (C/S) 

FILL-COLOR2 Yes (C/S) 

FILL-PERCENT Yes (C/S) 

FILLER Yes 

FINAL Yes 

FINALLY No 

FINISH-REASON Yes (C/S) 

FIRST Yes 

FIXED Yes 

FIXED-FONT Yes 

FIXED-WIDTH Yes (C/S) 

FLAT Yes (C/S) 

FLAT-BUTTONS Yes (C/S) 

FLOAT Yes FLOAT-SHORT 
FLOAT-BINARY-128 No 

FLOAT-BINARY-32 No 

FLOAT-BINARY-64 No 

FLOAT-DECIMAL-16 Yes 

FLOAT-DECIMAL-34 Yes 

FLOAT-EXTENDED No 

FLOAT-INFINITY No 

FLOAT-LONG Yes DOUBLE 
FLOAT-NOT-A-NUMBER No (C/S) 

FLOAT-SHORT Yes FLOAT 
FLOATING Yes 

FONT Yes 

FOOTING Yes 

FOR Yes 

FOREGROUND-COLOR Yes (C/S) FOREGROUND-COLOUR 
FOREGROUND-COLOUR Yes FOREGROUND-COLOR 
FOREVER Yes (C/S) 

FORMAT No 

FRAME Yes (C/S) 

FRAMED Yes (C/S) 

FREE Yes 

FROM Yes 

FULL Yes (C/S) LENGTH-CHECK 
FULL-HEIGHT Yes (C/S) 
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FUNCTION Yes 
FUNCTION-ID Yes 
FUNCTION-POINTER No 
GENERATE Yes 

GET No 
GIVING Yes 
GLOBAL Yes 

GO Yes 
GO-BACK Yes (C/S) 
GO-FORWARD Yes (C/S) 
GO-HOME Yes (C/S) 
GO-SEARCH Yes (C/S) 
GOBACK Yes 
GRAPHICAL Yes (C/S) 
GREATER Yes 

GRID Yes (C/S) 
GROUP Yes 
GROUP-USAGE No 
GROUP-VALUE Yes (C/S) 
HANDLE Yes 
HAS-CHILDREN Yes (C/S) 
HEADING Yes 
HEADING-COLOR Yes (C/S) 
HEADING-DIVIDER-COLOR Yes (C/S) 
HEADING-FONT Yes (C/S) 
HEAVY Yes (C/S) 
HEIGHT-IN-CELLS Yes (C/S) 
HEX No (C/S) 
HIDDEN-DATA Yes (C/S) 
HIGH-COLOR Yes (C/S) 
HIGH-VALUE Yes HIGH-VALUES 
HIGH-VALUES Yes HIGH-VALUE 
HIGHLIGHT Yes (C/S) 
HOT-TRACK Yes (C/S) 
HSCROLL Yes (C/S) 
HSCROLL-POS Yes (C/S) 
I-0 Yes 
I-O-CONTROL Yes 

ICON Yes (C/S) 
ID Yes 
IDENTIFICATION Yes 
IDENTIFIED Yes 

IF Yes 
IGNORE Yes 
IGNORING Yes (C/S) 
IMPLEMENTS No (C/S) 
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IN 
INDEPENDENT 
INDEX 

INDEXED 
INDICATE 
INHERITS 
INITIAL 
INITIALISE 
INITIALISED 
INITIALIZE 
INITIALIZED 
INITIATE 

INPUT 
INPUT-OUTPUT 
INQUIRE 
INSERT-ROWS 
INSERTION-INDEX 
INSPECT 
INSTALLATION 
INTERFACE 
INTERFACE-ID 
INTERMEDIATE 
INTO 

INTRINSIC 
INVALID 

INVOKE 

IS 
ITEM 
ITEM-TEXT 
ITEM-TO-ADD 
ITEM-TO-DELETE 
ITEM-TO-EMPTY 
ITEM-VALUE 
JSON 
JUST 
JUSTIFIED 
KEPT 

KEY 

KEYBOARD 
LABEL 
LABEL-OFFSET 
LARGE-FONT 
LARGE-OFFSET 
LAST 
LAST-ROW 
LAYOUT-DATA 
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Yes (C/S) 


Yes (C/S) 


Yes (C/S) 
Yes 
Yes (C/S) 
Yes 
Yes (C/S) 
Yes 
Yes (C/S) 
Yes (C/S) 
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INITIALIZE 
INITIALIZED 
INITIALISE 
INITIALISED 


JUSTIFIED 
JUST 


736 


LAYOUT-MANAGER 
LC_ALL 
LC_COLLATE 
LC_CTYPE 
LC_MESSAGES 
LC_MONETARY 
LC_NUMERIC 
LC_TIME 
LEADING 
LEADING-SHIFT 
LEAVE 

LEFT 

LEFT- JUSTIFY 
LEFT-TEXT 
LEFTLINE 
LENGTH 
LENGTH-CHECK 
LESS 

LIKE 

LIMIT 

LIMITS 

LINAGE 
LINAGE-COUNTER 
LINE 
LINE-COUNTER 
LINE-SEQUENTIAL 
LINES 
LINES-AT-ROOT 
LINKAGE 
LIST-BOX 
LM-RESIZE 

LOC 
LOCAL-STORAGE 
LOCALE 
LOCATION 

LOCK 
LOCK-HOLDING 
LONG-DATE 
LOW-COLOR 
LOW-VALUE 
LOW-VALUES 
LOWER 

LOWERED 
LOWLIGHT 
MAGNETIC-TAPE 
MANUAL 


Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 

Yes 

Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 


FULL 


LOW-VALUES 
LOW-VALUE 
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MASS-UPDATE 
MASTER- INDEX 
MAX-LINES 
MAX-PROGRESS 
MAX-TEXT 
MAX-VAL 
MEDIUM-FONT 
MEMORY 

MENU 

MERGE 

MESSAGE 
MESSAGE-TAG 
METHOD 
METHOD-ID 
MIN-VAL 

MINUS 

MODE 

MODIFY 

MODULES 

MOVE 

MULTILINE 
MULTIPLE 
MULTIPLY 

NAME 

NAMED 

NAMESPACE 
NAMESPACE-PREFIX 
NAT 

NATIONAL 
NATIONAL-EDITED 
NATIVE 
NAVIGATE-URL 
NEAREST-AWAY-FROM-ZERO 
NEAREST-EVEN 
NEAREST-TOWARD-ZERO 
NEGATIVE 

NESTED 

NEW 

NEXT 

NEXT-ITEM 

NO 

NO-AUTO-DEF AULT 
NO-AUTOSEL 
NO-BOX 
NO-DIVIDERS 
NO-ECHO 
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Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 

Yes (C/S) 


Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 


Yes (C/S) 
Yes 

Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 
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NO-F4 

NO-FOCUS 
NO-GROUP-TAB 
NO-KEY-LETTER 
NO-SEARCH 
NO-UPDOWN 
NOMINAL 

NONE 

NONNUMERIC 
NORMAL 

NOT 

NOTAB 

NOTHING 

NOTIFY 
NOTIFY-CHANGE 
NOTIFY-DBLCLICK 
NOTIFY-SELCHANGE 
NULL 

NULLS 
NUM-COL-HEADINGS 
NUM-ROWS 

NUMBER 

NUMBERS 

NUMERIC 
NUMERIC-EDITED 
OBJECT 
OBJECT-COMPUTER 
OBJECT-REFERENCE 
OCCURS 

OF 

OFF 

OK-BUTTON 
OMITTED 

ON 

ONLY 

OPEN 

OPTIONAL 
OPTIONS 

OR 

ORDER 
ORGANISATION 
ORGANIZATION 
OTHER 

OTHERS 

OUTPUT 

OVERFLOW 


Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
No (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 

Yes (C/S) 
Yes 

Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 


Yes (C/S) 


Yes (C/S) 


NULLS 
NULL 


ORGANIZATION 
ORGANISATION 
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OVERLAP-LEFT 
OVERLAP-TOP 
OVERLINE 
OVERRIDE 
PACKED-DECIMAL 
PADDING 

PAGE 
PAGE-COUNTER 
PAGE-SETUP 
PAGED 
PARAGRAPH 
PARENT 

PARSE 

PASCAL 
PASSWORD 
PERFORM 
PERMANENT 

PF 

PH 

PHYSICAL 

PIC 

PICTURE 

PIXEL 

PIXELS 
PLACEMENT 
PLUS 

POINTER 
POP-UP 

POS 

POSITION 
POSITION-SHIFT 
POSITIVE 

PREF IXED 
PRESENT 
PREVIOUS 
PRINT 
PRINT-NO-PROMPT 
PRINT-PREVIEW 
PRINTER 
PRINTER-1 
PRINTING 
PRIORITY 
PROCEDURE 
PROCEDURE-POINTER 
PROCEDURES 
PROCEED 
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Yes (C/S) OVERLAP-TOP 
Yes (C/S) OVERLAP-LEFT 


Yes PICTURE 
Yes PIC 

Yes (C/S) PIXELS 
Yes PIXEL 


Yes PROGRAM-POINTER 
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PROCESSING Yes (C/S) 
PROGRAM Yes 
PROGRAM-ID Yes 
PROGRAM-POINTER Yes PROCEDURE-POINTER 
PROGRESS Yes (C/S) 
PROHIBITED Yes (C/S) 
PROMPT Yes 
PROPERTIES Yes (C/S) 
PROPERTY Yes 
PROTECTED Yes (C/S) 
PROTOTYPE No 
PURGE Yes 
PUSH-BUTTON Yes (C/S) 
QUERY-INDEX Yes (C/S) 
QUEUE Yes 
QUOTE Yes QUOTES 
QUOTES Yes QUOTE 
RADIO-BUTTON Yes (C/S) 
RAISE Yes 
RAISED Yes (C/S) 
RAISING No 
RANDOM Yes 

RD Yes 

READ Yes 
READ-ONLY Yes (C/S) 
READERS Yes (C/S) 
RECEIVE Yes 
RECEIVED Yes 
RECORD Yes 
RECORD-DATA Yes (C/S) 
RECORD-OVERFLOW Yes (C/S) 
RECORD-TO-ADD Yes (C/S) 
RECORD-TO-DELETE Yes (C/S) 
RECORDING Yes 
RECORDS Yes 
RECURSIVE Yes (C/S) 
REDEFINES Yes 

REEL Yes 
REFERENCE Yes 
REFERENCES Yes 
REFRESH Yes (C/S) 
REGION-COLOR Yes (C/S) 
RELATION No (C/S) 
RELATIVE Yes 
RELEASE Yes 
REMAINDER Yes 
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REMARKS 
REMOVAL 
RENAMES 
REORG-CRITERIA 
REPEATED 
REPLACE 
REPLACING 
REPORT 
REPORTING 
REPORTS 
REPOSITORY 
REQUIRED 
REREAD 

RERUN 

RESERVE 

RESET 
RESET-GRID 
RESET-LIST 
RESET-TABS 
RESUME 

RETRY 

RETURN 
RETURNING 
REVERSE 
REVERSE-VIDEO 
REVERSED 
REWIND 
REWRITE 

RF 

RH 

RIGHT 
RIGHT-ALIGN 
RIGHT-JUSTIFY 
RIMMED 
ROLLBACK 
ROUNDED 
ROUNDING 
ROW-COLOR 
ROW-COLOR-PATTERN 
ROW-DIVIDERS 
ROW-FONT 
ROW-HEADINGS 
ROW-PROTECTION 
RUN 
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Yes (C/S) 


Yes (C/S) 


Yes (C/S) EMPTY-CHECK 
Yes (C/S) 

Yes (C/S) 

Yes 

Yes 

Yes (C/S) 

Yes (C/S) 

Yes (C/S) 

No 


Yes (C/S) 
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SAVE-AS Yes (C/S) 
SAVE-AS-NO-PROMPT Yes (C/S) 
SCREEN Yes 
SCROLL Yes (C/S) 
SCROLL-BAR Yes (C/S) 
SD Yes 
SEARCH Yes 
SEARCH-OPTIONS Yes (C/S) 
SEARCH-TEXT Yes (C/S) 
SECONDS Yes (C/S) 
SECTION Yes 
SECURE Yes (C/S) 
SECURITY Yes (C/S) 
SEGMENT Yes 
SEGMENT-LIMIT Yes 
SELECT Yes 
SELECT-ALL Yes (C/S) 
SELECTION-INDEX Yes (C/S) 
SELECTION-TEXT Yes (C/S) 
SELF No 
SELF-ACT Yes (C/S) 
SEND Yes 
SENTENCE Yes 
SEPARATE Yes 
SEPARATION Yes (C/S) 
SEQUENCE Yes 
SEQUENTIAL Yes 
SET Yes 
SHADING Yes (C/S) 
SHADOW Yes (C/S) 
SHARING Yes 
SHORT-DATE Yes (C/S) 
SHOW-LINES Yes (C/S) 
SHOW-NONE Yes (C/S) 
SHOW-SEL-ALWAYS Yes (C/S) 
SIGN Yes 
SIGNED Yes 
SIGNED-INT Yes 
SIGNED-LONG Yes 
SIGNED-SHORT Yes 
SIZE Yes 
SMALL-FONT Yes 
SORT Yes 
SORT-MERGE Yes 
SORT-ORDER Yes (C/S) 
SOURCE Yes 
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SOURCE-COMPUTER 
SOURCES 

SPACE 
SPACE-FILL 
SPACES 
SPECIAL-NAMES 
SPINNER 

SQUARE 

STACK 

STANDARD 
STANDARD-1 
STANDARD-2 
STANDARD-BINARY 


STANDARD-DECIMAL 


START 
START-X 
START-Y 
STATEMENT 
STATIC 
STATIC-LIST 
STATUS 
STATUS-BAR 
STATUS-TEXT 
STDCALL 
STEP 

STOP 

STRING 
STRONG 
STYLE 
SUB-QUEUE-1 
SUB-QUEUE-2 
SUB-QUEUE-3 
SUBTRACT 
SUBWINDOW 
SUM 
SUPER 

SUPPRESS 
SYMBOL 
SYMBOLIC 

SYNC 
SYNCHRONISED 
SYNCHRONIZED 
SYSTEM-DEFAULT 
SYSTEM-INFO 
SYSTEM-OFFSET 
TAB 
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Yes SPACES 
Yes SPACE 


Yes (C/S) 
Yes (C/S) 
No (C/S) 


Yes (C/S) 
Yes (C/S) 
Yes 

Yes (C/S) 
Yes (C/S) 
No (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 

Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 

Yes 

No (C/S) 
Yes (C/S) 


Yes SYNCHRONISED, SYNCHRONIZED 
Yes SYNC, SYNCHRONIZED 
Yes SYNC, SYNCHRONISED 


Yes (C/S) 


Yes 
Yes (C/S) 
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TAB-TO-ADD Yes (C/S) 
TAB-TO-DELETE Yes (C/S) 
TABLE Yes 
TALLYING Yes 

TAPE Yes (C/S) 
TEMPORARY Yes (C/S) 
TERMINAL-INFO Yes (C/S) 
TERMINATE Yes 
TERMINATION-VALUE Yes (C/S) 
TEST Yes 

TEXT Yes 

THAN Yes 

THEN Yes 
THREAD Yes 
THREADS Yes 
THROUGH Yes THRU 
THRU Yes THROUGH 
THUMB-POSITION Yes (C/S) 
TILED-HEADINGS Yes (C/S) 
TIME Yes 
TIME-OUT Yes (C/S) TIMEOUT 
TIMEOUT Yes TIME-OUT 
TIMES Yes 
TITLE Yes (C/S) 
TITLE-POSITION Yes (C/S) 
TO Yes 

TOP Yes 
TOP-LEVEL No (C/S) 
TOWARD-GREATER Yes (C/S) 
TOWARD-LESSER Yes (C/S) 
TRACK Yes (C/S) 
TRACK-AREA Yes (C/S) 
TRACK-LIMIT Yes (C/S) 
TRACKS Yes (C/S) 
TRADITIONAL-FONT Yes 
TRAILING Yes 
TRAILING-SHIFT Yes (C/S) 
TRAILING-SIGN No 
TRANSFORM Yes 
TRANSPARENT Yes (C/S) 
TREE-VIEW Yes (C/S) 
TRUE Yes 
TRUNCATION Yes (C/S) 
TYPE Yes 
TYPEDEF Yes 

U Yes (C/S) 
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UCcS-4 
UNBOUNDED 
UNDERLINE 
UNFRAMED 
UNIT 
UNIVERSAL 
UNLOCK 
UNSIGNED 
UNSIGNED-INT 
UNSIGNED-LONG 
UNSIGNED-SHORT 
UNSORTED 
UNSTRING 
UNTIL 

UP 

UPDATE 
UPDATERS 
UPON 

UPPER 

USAGE 

USE 

USE-ALT 
USE-RETURN 
USE-TAB 

USER 
USER-DEFAULT 
USING 

UTF-16 

UTF-8 

V 

VAL-STATUS 
VALID 
VALIDATE 
VALIDATE-STATUS 
VALIDATING 
VALUE 
VALUE-FORMAT 
VALUES 
VARIABLE 
VARIANT 
VARYING 
VERTICAL 
VERY-HEAVY 
VIRTUAL-WIDTH 
VOLATILE 
VPADDING 
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Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 


Yes (C/S) 


Yes (C/S) 
Yes 
Yes (C/S) 
Yes 
Yes 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
Yes 
Yes 
Yes (C/S) 
Yes (C/S) 
Yes (C/S) 
No 


No 

Yes (C/S) 

Yes VALUES 
Yes (C/S) 

Yes VALUE 
Yes (C/S) 

Yes 

Yes 

Yes (C/S) 

Yes (C/S) 

Yes (C/S) 

Yes 

Yes (C/S) 


Appendix C1 - Grouped Word Lists by feature and function 


746 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


VSCROLL Yes (C/S) 

VSCROLL-BAR Yes (C/S) 

VSCROLL-POS Yes (C/S) 

VTOP Yes (C/S) 

WAIT Yes 

WEB-BROWSER Yes (C/S) 

WHEN Yes 

WIDTH Yes (C/S) 

WIDTH-IN-CELLS Yes (C/S) 

WINDOW Yes 

WITH Yes 

WORDS Yes 

WORKING-STORAGE Yes 

WRAP Yes (C/S) 

WRITE Yes 

WRITE-ONLY Yes (C/S) 

WRITE-VERIFY Yes (C/S) 

WRITERS Yes (C/S) 

X Yes (C/S) 

XML Yes 

XML-DECLARATION Yes (C/S) 

XML-SCHEMA Yes (C/S) 

XOR No 

Y Yes (C/S) 

YYYYDDD Yes (C/S) 

YYYYMMDD Yes (C/S) 

ZERO Yes ZEROES , ZEROS 
ZERO-FILL No (G/S) 

ZEROES Yes ZERO, ZEROS 
ZEROS Yes ZERO, ZEROES 


Extra (obsolete) context sensitive words 


AUTHOR, DATE-COMPILED, DATE-MODIFIED, DATE-WRITTEN, INSTALLATION, REMARKS, 
SECURITY 


Internal registers 


Register Implemented Definition 

> ADDRESS OF’ phrase Yes USAGE POINTER 

COB-CRT-STATUS Yes PICTURE 9(4) USAGE DISPLAY 
VALUE ZERO 

DEBUG-ITEM Yes PICTURE X(n) USAGE DISPLAY 

> LENGTH OF’ phrase Yes CONSTANT USAGE BINARY-LONG 

NUMBER-OF-CALL-PARAMETERS Yes USAGE BINARY-LONG 
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RETURN-CODE 


SORT-RETURN 


TALLY 


WHEN-COMPILED 


XML-CODE 


XML-EVENT 


XML-INFORMATION 


XML-NAMESPACE 


XML-NAMESPACE-PREFIX 


XML-NNAMESPACE 


XML-NNAMESPACE-PREFIX 


XML-NTEXT 


XML-TEXT 
JSON-CODE 


JSON-STATUS 
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Yes GLOBAL 
USAGE DISPLAY 
PICTURE X(30) 
VALUE SPACE 
Yes GLOBAL 
PICTURE S9(9) 
USAGE BINARY 
VALUE 0 

Yes GLOBAL PIC 
X ANY LENGTH 
Yes GLOBAL PIC 
X ANY LENGTH 
Yes GLOBAL PIC 
N ANY LENGTH 
Yes GLOBAL PIC 
N ANY LENGTH 
Yes GLOBAL PIC 
N ANY LENGTH 
Yes GLOBAL PIC 
X ANY LENGTH 
Yes 


Yes 


GLOBAL USAGE BINARY-LONG 
VALUE ZERO 

GLOBAL USAGE BINARY-LONG 
VALUE ZERO 

GLOBAL PICTURE 9(5) USAGE 
BINARY VALUE ZERO 

CONSTANT PICTURE X(16) USAGE 
DISPLAY 

GLOBAL PICTURE S9(9) USAGE 
BINARY VALUE 0 


GLOBAL PICTURE S9(9) USAGE 
BINARY VALUE 0 
GLOBAL PICTURE S9(9) USAGE 
BINARY VALUE 0 
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Appendix C2 - Intrinsic Functions 


The following list of intrinsic functions was extracted from cobc --list-intrinsics and 
shows the names of the available functions, an implementation note and the number of 
parameters. 


Intrinsic Function Implemented Parameters 
ABS Yes 1 
ACOS Yes 1 
ANNUITY Yes 2 
ASIN Yes 1 
ATAN Yes 1 
BASECONVERT No 3 
BIT-OF Yes 1 
BIT-TO-CHAR Yes 1 
BOOLEAN-OF-INTEGER No 2 
BYTE-LENGTH Yes 1-2 
CHAR Yes 1 
CHAR-NATIONAL No 1 
COMBINED-DATETIME Yes 2 
CONCAT Yes Unlimited 
CONCATENATE Yes Unlimited 
CONTENT-LENGTH Yes 1 
CONTENT-OF Yes 1-2 
CONVERT No 3 
cos Yes 1 
CURRENCY-SYMBOL Yes 0 
CURRENT-DATE Yes 0 
DATE-OF-INTEGER Yes 1 
DATE-TO-YYYYMMDD Yes 1-3 
DAY-OF-INTEGER Yes 1 
DAY-TO-YYYYDDD Yes 1-3 
DISPLAY-OF No 1-2 
E Yes 0 
EXCEPTION-FILE Yes 0 
EXCEPTION-FILE-N No 0 
EXCEPTION-LOCATION Yes 0 
EXCEPTION-LOCATION-N No 0 
EXCEPTION-STATEMENT Yes 0) 
EXCEPTION-STATUS Yes 0 
EXP Yes 1 
EXP10 Yes 1 
FACTORIAL Yes 1 
FIND-STRING No 7-2 
FORMATTED-CURRENT-DATE Yes 1 
FORMATTED-DATE Yes 2 


15 January 2023 Appendix C2 - Intrinsic Functions 


750 GnuCOBOL 3.2 [15 January 2023 at 16:30 GMT.] Programmer’s Guide 


FORMATTED-DATETIME 
FORMATTED-TIME 
FRACTION-PART 

HEX-OF 

HEX-TO-CHAR 
HIGHEST-ALGEBRAIC 
INTEGER 
INTEGER-OF-BOOLEAN 
INTEGER-OF-DATE 
INTEGER-OF-DAY 
INTEGER-OF-FORMATTED-DATE 
INTEGER-PART 

LENGTH 

LENGTH-AN 
LOCALE-COMPARE Yes 2 - 3 
LOCALE-DATE 
LOCALE-TIME 
LOCALE-TIME-FROM-SECONDS 
LOG 

LOG10 

LOWER-CASE 
LOWEST-ALGEBRAIC 

MAX 

MEAN 

MEDIAN 

MIDRANGE 

MIN 

MOD 

MODULE-CALLER-ID 
MODULE-DATE 
MODULE-FORMATTED-DATE 
MODULE-ID 

MODULE-NAME 
MODULE-PATH 
MODULE-SOURCE 
MODULE-TIME 
MONETARY-DECIMAL-POINT 
MONETARY-THOUSANDS-SEPARATOR 
NATIONAL-OF 
NUMERIC-DECIMAL-POINT 
NUMERIC-THOUSANDS-SEPARATOR 
NUMVAL 

NUMVAL-C 

NUMVAL-F 

ORD 

ORD-MAX 
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ORD-MIN 

Pi 
PRESENT-VALUE 
RANDOM 

RANGE 

REM 

REVERSE 


SECONDS-FROM-FORMATTED-TIME 
SECONDS-PAST-MIDNIGHT 


SIGN 
SIN 
SQRT 


STANDARD-COMPARE 
STANDARD-DEVIATION 
STORED-CHAR-LENGTH 


SUBSTITUTE 


SUBSTITUTE-CASE 


SUM 
TAN 


TEST-DATE-YYYYMMDD 
TEST-DAY-YYYYDDD 
TEST-FORMATTED-DATETIME 


TEST-NUMVAL 
TEST-NUMVAL-C 
TEST-NUMVAL-F 
TRIM 
UPPER-CASE 
VARIANCE 
WHEN-COMPILED 
YEAR-TO-YYYY 
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Unlimited 
0 
Unlimited 
0-1 
Unlimited 
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2-4 
Unlimited 
1 
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Appendix C3 - System routines 


The following list of system routines was extracted from cobc --list-system and shows 
the names of the available system routines along with the number of parameters. 


System routine 
SYSTEM 

CBL_AND 
CBL_ALARM_SOUND 
CBL_BELL_SOUND 
CBL_CHANGE_DIR 
CBL_CHECK_FILE_EXIST 
CBL_CLOSE_FILE 
CBL_COPY_FILE 
CBL_CREATE_DIR 
CBL_CREATE_FILE 
CBL_DELETE_DIR 
CBL_DELETE_FILE 
CBL_EQ 
CBL_ERROR_PROC 
CBL_EXIT_PROC 
CBL_FLUSH_FILE 
CBL_GET_CSR_POS 
CBL_GET_CURRENT_DIR 
CBL_GET_SCR_SIZE 
CBL_IMP 

CBL_NIMP 

CBL_NOR 

CBL_NOT 
CBL_OPEN_FILE 
CBL_OR 
CBL_READ_FILE 
CBL_READ_KBD_CHAR 
CBL_RENAME_FILE 
CBL_SET_CSR_POS 
CBL_TOLOWER 
CBL_TOUPPER 
CBL_WRITE_FILE 
CBL_XOR 
CBL_GC_FORK 
CBL_GC_GETOPT 
CBL_GC_HOSTED 
CBL_GC_NANOSLEEP 
CBL_GC_PRINTABLE 
CBL_GC_WAITPID 
CBL_OC_GETOPT 
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CBL_OC_HOSTED 
CBL_OC_NANOSLEEP 


C$CALLEDBY 
C$CHDIR 
C$COPY 
C$DELETE 
C$FILEINFO 
C$GETPID 
C$JUSTIFY 
C$MAKEDIR 
C$NARG 
C$PARAMSIZE 
C$PRINTABLE 
C$SLEEP 
C$TOLOWER 
C$TOUPPER 
EXTFH 

x"g1" 

X"E4" 

X"E5" 

X"F4" 

X"F5" 
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Appendix C4 - System names 


The following list of system names was extracted from cobc --list-mnemonics and shows 
the system names categorized by their type. 


System names: device 


SYSIN, SYSIPT, STDIN, SYSOUT, SYSLIST, SYSLST, SYSPCH, SYSPUNCH, STDOUT, PRINT, 
PRINTER, PRINTER-1, SYSERR, STDERR, CONSOLE, ALTERNATE-CONSOLE, ALTERNATE CONSOLE 


System names: feature 


C01, C02, C03, C04, C05, C06, CO7, CO8, CO9, C10, C11, C12, $01, $02, $03, $04, S05, CSP, 
FORMFEED, TOP, CALL-CONVENTION 


System names: switch 


SWITCH-0, SWITCH-1, SWITCH-2, SWITCH-3, SWITCH-4, SWITCH-5, SWITCH-6, SWITCH-7, 
SWITCH-8, SWITCH-9, SWITCH-10, SWITCH-11, SWITCH-12, SWITCH-13, SWITCH-14, 
SWITCH-15, SWITCH-16, SWITCH-17, SWITCH-18, SWITCH-19, SWITCH-20, SWITCH-21, 
SWITCH-22, SWITCH-23, SWITCH-24, SWITCH-25, SWITCH-26, SWITCH-27, SWITCH-28, 
SWITCH-29, SWITCH-30, SWITCH-31, SWITCH-32, SWITCH-33, SWITCH-34, SWITCH-35, 
SWITCH-36 
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Appendix C5 - Exceptions 


The following list of exceptions names was extracted from cobc --list-exceptions and 


shows the names by type. 


Exception Name 
EC-ALL 

EC-ARGUMENT 
EC-ARGUMENT-FUNCTION (f) 
EC-ARGUMENT-IMP 

EC-BOUND 
EC-BOUND-FUNC-RET-VALUE 
EC-BOUND-IMP 
EC-BOUND-ODO (f) 
EC-BOUND-OVERFLOW (f) 
EC-BOUND-PTR (f) 
EC-BOUND-REF-MOD (f) 
EC-BOUND-SET (f) 
EC-BOUND-SUBSCRIPT (f) 
EC-BOUND-TABLE-LIMIT (f) 

EC-CONTINUE 
EC-CONTINUE-IMP 
EC-CONTINUE-LESS-THAN-ZERO 

EC-DATA 
EC-DATA-CONVERSION 
EC-DATA-IMP 
EC-DATA-INCOMPATIBLE (f) 
EC-DATA-NOT-FINITE (f) 
EC-DATA-OVERFLOW (f) 
EC-DATA-PTR-NULL (£) 

EC-EXTERNAL 
EC-EXTERNAL-DATA-MISMATCH (f) 
EC-EXTERNAL-FILE-MISMATCH (f) 
EC-EXTERNAL-FORMAT-CONFLICT (£) 
EC-EXTERNAL-IMP 

EC-FLOW 
EC-FLOW-APPLY-COMMIT (f) 
EC-FLOW-COMMIT (f) 
EC-FLOW-GLOBAL-EXIT (£) 
EC-FLOW-GLOBAL-GOBACK (f) 
EC-FLOW-IMP 
EC-FLOW-RELEASE (f) 
EC-FLOW-REPORT (f) 
EC-FLOW-RETURN (f) 
EC-FLOW-ROLLBACK (£) 
EC-FLOW-SEARCH (f) 
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EC-FLOW-USE (£) 

EC-FUNCTION 
EC-FUNCTION-ARG-OMITTED (f) 
EC-FUNCTION-IMP 
EC-FUNCTION-NOT-FOUND (f) 
EC-FUNCTION-PTR-INVALID (f) 
EC-FUNCTION-PTR-NULL (f) 

EC-I-0 
EC-1-0-AT-END 
EC-1I-0-EOP 
EC-1I-0-EOP-OVERFLOW 
EC-1I-O-FILE-SHARING 
EC-1-0-IMP 
EC-1I-O-INVALID-KEY 
EC-I-O-LINAGE (f) 
EC-I-O-LOGIC-ERROR (f) 
EC-I-O-PERMANENT-ERROR (f) 
EC-I-O0-RECORD-CONTENT (f) 
EC-1I-O-RECORD-OPERATION 
EC-1I-O-RECORD-WARNING 

EC-IMP 
EC-IMP-ACCEPT 
EC-IMP-DISPLAY 
EC-IMP-UTC-UNKNOWN (#£) 
EC-IMP-FEATURE-DISABLED 
EC-IMP-FEATURE-MISSING 

EC-LOCALE 
EC-LOCALE-IMP 
EC-LOCALE-INCOMPATIBLE 
EC-LOCALE-INVALID (f) 
EC-LOCALE-INVALID-PTR (f) 
EC-LOCALE-MISSING (f) 
EC-LOCALE-SIZE (f) 

EC-MCS 
EC-MCS-ABNORMAL-TERMINATION 
EC-MCS-IMP 
EC-MCS-INVALID-TAG 
EC-MCS-MESSAGE-LENGTH 
EC-MCS-NO-REQUESTER 
EC-MCS-NO-SERVER 
EC-MCS-NORMAL-TERMINATION 
EC-MCS-REQUESTOR-FAILED 

EC-00 
EC-O0-ARG-OMITTED (f) 
EC-OO-CONFORMANCE (f) 
EC-O0-EXCEPTION (f) 
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EC-0O0-IMP 
EC-OO-METHOD (f) 
EC-OO-NULL (f) 
EC-O0-RESOURCE (f£) 
EC-OO-UNIVERSAL (f) 
EC-ORDER 
EC-ORDER-IMP 
EC-ORDER-NOT-SUPPORTED (f) 
EC-OVERFLOW 
EC-OVERFLOW-IMP 
EC-OVERFLOW-STRING 
EC-OVERFLOW-UNSTRING 
EC-PROGRAM 
EC-PROGRAM-ARG-MISMATCH (f) 
EC-PROGRAM-ARG-OMITTED (£) 


EC-PROGRAM-CANCEL-ACTIVE (f£) 


EC-PROGRAM-IMP 
EC-PROGRAM-NOT-FOUND (f) 
EC-PROGRAM-PTR-NULL (f) 


EC-PROGRAM-RECURSIVE-CALL (f) 


EC-PROGRAM-RESOURCES (f) 
EC-RAISING 
EC-RAISING-IMP 


EC-RAISING-NOT-SPECIFIED (f) 


EC-RANGE 
EC-RANGE-IMP 
EC-RANGE-INDEX (f) 
EC-RANGE-INSPECT-SIZE (f) 
EC-RANGE-INVALID 


EC-RANGE-PERFORM-VARYING (f) 


EC-RANGE-PTR (f) 
EC-RANGE-SEARCH- INDEX 
EC-RANGE-SEARCH-NO-MATCH 
EC-REPORT 
EC-REPORT-ACTIVE (£) 


EC-REPORT-COLUMN-OVERLAP (f) 


EC-REPORT-FILE-MODE (f) 
EC-REPORT-IMP 
EC-REPORT-INACTIVE (f) 
EC-REPORT-LINE-OVERLAP 
EC-REPORT-NOT-TERMINATED 
EC-REPORT-PAGE-LIMIT 
EC-REPORT-PAGE-WIDTH 
EC-REPORT-SUM-SIZE (f) 
EC-REPORT-VARYING (f) 
EC-SCREEN 
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EC-SCREEN-FIELD-OVERLAP 
EC-SCREEN-IMP 
EC-SCREEN-ITEM-TRUNCATED 
EC-SCREEN-LINE-NUMBER 
EC-SCREEN-STARTING-COLUMN 

EC-SIZE 
EC-SIZE-ADDRESS (f) 
EC-SIZE-EXPONENTIATION (£) 
EC-SIZE-IMP 
EC-SIZE-OVERFLOW (f) 
EC-SIZE-TRUNCATION (f£) 
EC-SIZE-UNDERFLOW (f) 
EC-SIZE-ZERO-DIVIDE (£) 

EC-SORT-MERGE 
EC-SORT-MERGE-ACTIVE (f) 
EC-SORT-MERGE-FILE-OPEN (f) 
EC-SORT-MERGE- IMP 
EC-SORT-MERGE-RELEASE (f) 
EC-SORT-MERGE-RETURN (f) 
EC-SORT-MERGE-SEQUENCE (f£) 

EC-STORAGE 
EC-STORAGE-IMP 
EC-STORAGE-NOT-ALLOC 
EC-STORAGE-NOT-AVAIL 

EC-USER 

EC-VALIDATE 
EC-VALIDATE-CONTENT 
EC-VALIDATE-FORMAT 
EC-VALIDATE-IMP 
EC-VALIDATE-RELATION 
EC-VALIDATE-VARYING (f) 

EC-XML 
EC-XML-CODESET (f) 
EC-XML-CODESET-CONVERSION (f) 
EC-XML-COUNT (f) 
EC-XML-DOCUMENT-TYPE (f) 
EC-XML-IMPLICIT-CLOSE (f) 
EC-XML-INVALID (£) 
EC-XML-NAMESPACE (£) 
EC-XML-STACKED-OPEN (£) 
EC-XML-RANGE (f) 

EC-XML-IMP (£) 

EC- JSON 

EC-JSON-IMP (£) 
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End of Appendix C — Grouped Reserved Word List 
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Appendix D - GNU Free Documentation License 


Version 1.3, 3 November 2008 


Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 
https://fsf.org/ 


Everyone is permitted to copy and distribute verbatim copies 
of this license document, but changing it is not allowed. 


0. PREAMBLE 


763 


The purpose of this License is to make a manual, textbook, or other functional and 
useful document free in the sense of freedom: to assure everyone the effective freedom 
to copy and redistribute it, with or without modifying it, either commercially or non- 
commercially. Secondarily, this License preserves for the author and publisher a way 
to get credit for their work, while not being considered responsible for modifications 


made by others. 


This License is a kind of “copyleft”, which means that derivative works of the document 
must themselves be free in the same sense. It complements the GNU General Public 


License, which is a copyleft license designed for free software. 


We have designed this License in order to use it for manuals for free software, because 
free software needs free documentation: a free program should come with manuals 
providing the same freedoms that the software does. But this License is not limited to 
software manuals; it can be used for any textual work, regardless of subject matter or 


whether it is published as a printed book. We recommend this License principally 
works whose purpose is instruction or reference. 


1. APPLICABILITY AND DEFINITIONS 


for 


This License applies to any manual or other work, in any medium, that contains a 
notice placed by the copyright holder saying it can be distributed under the terms 
of this License. Such a notice grants a world-wide, royalty-free license, unlimited in 
duration, to use that work under the conditions stated herein. The “Document”, 
below, refers to any such manual or work. Any member of the public is a licensee, and 
is addressed as “you”. You accept the license if you copy, modify or distribute the work 


in a way requiring permission under copyright law. 


A “Modified Version” of the Document means any work containing the Document or 
a portion of it, either copied verbatim, or with modifications and/or translated into 


another language. 


A “Secondary Section” is a named appendix or a front-matter section of the Document 
that deals exclusively with the relationship of the publishers or authors of the Document 
to the Document’s overall subject (or to related matters) and contains nothing that 
could fall directly within that overall subject. (Thus, if the Document is in part a 
textbook of mathematics, a Secondary Section may not explain any mathematics.) The 
relationship could be a matter of historical connection with the subject or with related 
matters, or of legal, commercial, philosophical, ethical or political position regarding 


them. 
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The “Invariant Sections” are certain Secondary Sections whose titles are designated, as 
being those of Invariant Sections, in the notice that says that the Document is released 
under this License. If a section does not fit the above definition of Secondary then it is 
not allowed to be designated as Invariant. The Document may contain zero Invariant 
Sections. If the Document does not identify any Invariant Sections then there are none. 
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover 
Texts or Back-Cover Texts, in the notice that says that the Document is released under 
this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may 
be at most 25 words. 

A “Transparent” copy of the Document means a machine-readable copy, represented 
in a format whose specification is available to the general public, that is suitable for 
revising the document straightforwardly with generic text editors or (for images com- 
posed of pixels) generic paint programs or (for drawings) some widely available drawing 
editor, and that is suitable for input to text formatters or for automatic translation to 
a variety of formats suitable for input to text formatters. A copy made in an otherwise 
Transparent file format whose markup, or absence of markup, has been arranged to 
thwart or discourage subsequent modification by readers is not Transparent. An image 
format is not Transparent if used for any substantial amount of text. A copy that is 
not “Transparent” is called “Opaque”. 

Examples of suitable formats for Transparent copies include plain ASCII without 
markup, Texinfo input format, LaTf@X input format, SGML or XML using a publicly 
available DTD, and standard-conforming simple HTML, PostScript or PDF designed 
for human modification. Examples of transparent image formats include PNG, XCF 
and JPG. Opaque formats include proprietary formats that can be read and edited 
only by proprietary word processors, SGML or XML for which the DTD and/or pro- 
cessing tools are not generally available, and the machine-generated HTML, PostScript 
or PDF produced by some word processors for output purposes only. 

The “Title Page” means, for a printed book, the title page itself, plus such following 
pages as are needed to hold, legibly, the material this License requires to appear in the 
title page. For works in formats which do not have any title page as such, “Title Page” 
means the text near the most prominent appearance of the work’s title, preceding the 
beginning of the body of the text. 

The “publisher” means any person or entity that distributes copies of the Document 
to the public. 

A section “Entitled XYZ” means a named subunit of the Document whose title either 
is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in 
another language. (Here XYZ stands for a specific section name mentioned below, such 
as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve 
the Title” of such a section when you modify the Document means that it remains a 
section “Entitled XYZ” according to this definition. 

The Document may include Warranty Disclaimers next to the notice which states that 
this License applies to the Document. These Warranty Disclaimers are considered to 
be included by reference in this License, but only as regards disclaiming warranties: 
any other implication that these Warranty Disclaimers may have is void and has no 
effect on the meaning of this License. 
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2. VERBATIM COPYING 


You may copy and distribute the Document in any medium, either commercially or 
noncommercially, provided that this License, the copyright notices, and the license 
notice saying this License applies to the Document are reproduced in all copies, and 
that you add no other conditions whatsoever to those of this License. You may not use 
technical measures to obstruct or control the reading or further copying of the copies 
you make or distribute. However, you may accept compensation in exchange for copies. 
If you distribute a large enough number of copies you must also follow the conditions 
in section 3. 


You may also lend copies, under the same conditions stated above, and you may publicly 
display copies. 
3. COPYING IN QUANTITY 


If you publish printed copies (or copies in media that commonly have printed covers) of 
the Document, numbering more than 100, and the Document’s license notice requires 
Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all 
these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 
the back cover. Both covers must also clearly and legibly identify you as the publisher 
of these copies. The front cover must present the full title with all words of the title 
equally prominent and visible. You may add other material on the covers in addition. 
Copying with changes limited to the covers, as long as they preserve the title of the 
Document and satisfy these conditions, can be treated as verbatim copying in other 
respects. 


If the required texts for either cover are too voluminous to fit legibly, you should put 
the first ones listed (as many as fit reasonably) on the actual cover, and continue the 
rest onto adjacent pages. 


If you publish or distribute Opaque copies of the Document numbering more than 100, 
you must either include a machine-readable Transparent copy along with each Opaque 
copy, or state in or with each Opaque copy a computer-network location from which 
the general network-using public has access to download using public-standard network 
protocols a complete Transparent copy of the Document, free of added material. If 
you use the latter option, you must take reasonably prudent steps, when you begin 
distribution of Opaque copies in quantity, to ensure that this Transparent copy will 
remain thus accessible at the stated location until at least one year after the last time 
you distribute an Opaque copy (directly or through your agents or retailers) of that 
edition to the public. 


It is requested, but not required, that you contact the authors of the Document well 
before redistributing any large number of copies, to give them a chance to provide you 
with an updated version of the Document. 


4. MODIFICATIONS 


‘You may copy and distribute a Modified Version of the Document under the conditions 
of sections 2 and 3 above, provided that you release the Modified Version under precisely 
this License, with the Modified Version filling the role of the Document, thus licensing 
distribution and modification of the Modified Version to whoever possesses a copy of 
it. In addition, you must do these things in the Modified Version: 
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A. Use in the Title Page (and on the covers, if any) a title distinct from that of the 
Document, and from those of previous versions (which should, if there were any, 
be listed in the History section of the Document). You may use the same title as 
a previous version if the original publisher of that version gives permission. 


B. List on the Title Page, as authors, one or more persons or entities responsible for 
authorship of the modifications in the Modified Version, together with at least five 
of the principal authors of the Document (all of its principal authors, if it has fewer 
than five), unless they release you from this requirement. 


C. State on the Title page the name of the publisher of the Modified Version, as the 
publisher. 


D. Preserve all the copyright notices of the Document. 


E. Add an appropriate copyright notice for your modifications adjacent to the other 
copyright notices. 


F. Include, immediately after the copyright notices, a license notice giving the public 
permission to use the Modified Version under the terms of this License, in the form 
shown in the Addendum below. 


G. Preserve in that license notice the full lists of Invariant Sections and required Cover 
Texts given in the Document’s license notice. 


H. Include an unaltered copy of this License. 


I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item 
stating at least the title, year, new authors, and publisher of the Modified Version 
as given on the Title Page. If there is no section Entitled “History” in the Docu- 
ment, create one stating the title, year, authors, and publisher of the Document 
as given on its Title Page, then add an item describing the Modified Version as 
stated in the previous sentence. 


J. Preserve the network location, if any, given in the Document for public access to 
a Transparent copy of the Document, and likewise the network locations given in 
the Document for previous versions it was based on. These may be placed in the 
“History” section. You may omit a network location for a work that was published 
at least four years before the Document itself, or if the original publisher of the 
version it refers to gives permission. 


K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title 
of the section, and preserve in the section all the substance and tone of each of the 
contributor acknowledgements and/or dedications given therein. 


L. Preserve all the Invariant Sections of the Document, unaltered in their text and 
in their titles. Section numbers or the equivalent are not considered part of the 
section titles. 


M. Delete any section Entitled “Endorsements”. Such a section may not be included 
in the Modified Version. 


N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in 
title with any Invariant Section. 


O. Preserve any Warranty Disclaimers. 
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If the Modified Version includes new front-matter sections or appendices that qualify 
as Secondary Sections and contain no material copied from the Document, you may at 
your option designate some or all of these sections as invariant. To do this, add their 
titles to the list of Invariant Sections in the Modified Version’s license notice. These 
titles must be distinct from any other section titles. 


You may add a section Entitled “Endorsements”, provided it contains nothing but 
endorsements of your Modified Version by various parties—for example, statements of 
peer review or that the text has been approved by an organization as the authoritative 
definition of a standard. 


You may add a passage of up to five words as a Front-Cover Text, and a passage of up 
to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified 
Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be 
added by (or through arrangements made by) any one entity. If the Document already 
includes a cover text for the same cover, previously added by you or by arrangement 
made by the same entity you are acting on behalf of, you may not add another; but 
you may replace the old one, on explicit permission from the previous publisher that 
added the old one. 


The author(s) and publisher(s) of the Document do not by this License give permission 
to use their names for publicity for or to assert or imply endorsement of any Modified 
Version. 


5. COMBINING DOCUMENTS 


You may combine the Document with other documents released under this License, 
under the terms defined in section 4 above for modified versions, provided that you 
include in the combination all of the Invariant Sections of all of the original documents, 
unmodified, and list them all as Invariant Sections of your combined work in its license 
notice, and that you preserve all their Warranty Disclaimers. 


The combined work need only contain one copy of this License, and multiple identical 
Invariant Sections may be replaced with a single copy. If there are multiple Invariant 
Sections with the same name but different contents, make the title of each such section 
unique by adding at the end of it, in parentheses, the name of the original author or 
publisher of that section if known, or else a unique number. Make the same adjustment 
to the section titles in the list of Invariant Sections in the license notice of the combined 
work. 


In the combination, you must combine any sections Entitled “History” in the vari- 
ous original documents, forming one section Entitled “History”; likewise combine any 
sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You 
must delete all sections Entitled “Endorsements.” 


6. COLLECTIONS OF DOCUMENTS 


You may make a collection consisting of the Document and other documents released 
under this License, and replace the individual copies of this License in the various 
documents with a single copy that is included in the collection, provided that you 
follow the rules of this License for verbatim copying of each of the documents in all 
other respects. 
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You may extract a single document from such a collection, and distribute it individu- 
ally under this License, provided you insert a copy of this License into the extracted 
document, and follow this License in all other respects regarding verbatim copying of 
that document. 


AGGREGATION WITH INDEPENDENT WORKS 


A compilation of the Document or its derivatives with other separate and independent 
documents or works, in or on a volume of a storage or distribution medium, is called 
an “aggregate” if the copyright resulting from the compilation is not used to limit the 
legal rights of the compilation’s users beyond what the individual works permit. When 
the Document is included in an aggregate, this License does not apply to the other 
works in the aggregate which are not themselves derivative works of the Document. 


If the Cover Text requirement of section 3 is applicable to these copies of the Document, 
then if the Document is less than one half of the entire aggregate, the Document’s Cover 
Texts may be placed on covers that bracket the Document within the aggregate, or the 
electronic equivalent of covers if the Document is in electronic form. Otherwise they 
must appear on printed covers that bracket the whole aggregate. 


TRANSLATION 


Translation is considered a kind of modification, so you may distribute translations 
of the Document under the terms of section 4. Replacing Invariant Sections with 
translations requires special permission from their copyright holders, but you may 
include translations of some or all Invariant Sections in addition to the original versions 
of these Invariant Sections. You may include a translation of this License, and all the 
license notices in the Document, and any Warranty Disclaimers, provided that you 
also include the original English version of this License and the original versions of 
those notices and disclaimers. In case of a disagreement between the translation and 
the original version of this License or a notice or disclaimer, the original version will 
prevail. 


If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “His- 
tory”, the requirement (section 4) to Preserve its Title (section 1) will typically require 
changing the actual title. 


TERMINATION 


You may not copy, modify, sublicense, or distribute the Document except as expressly 
provided under this License. Any attempt otherwise to copy, modify, sublicense, or 
distribute it is void, and will automatically terminate your rights under this License. 


However, if you cease all violation of this License, then your license from a particular 
copyright holder is reinstated (a) provisionally, unless and until the copyright holder 
explicitly and finally terminates your license, and (b) permanently, if the copyright 
holder fails to notify you of the violation by some reasonable means prior to 60 days 
after the cessation. 


Moreover, your license from a particular copyright holder is reinstated permanently if 
the copyright holder notifies you of the violation by some reasonable means, this is the 
first time you have received notice of violation of this License (for any work) from that 
copyright holder, and you cure the violation prior to 30 days after your receipt of the 
notice. 
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10. 


11. 


Termination of your rights under this section does not terminate the licenses of parties 
who have received copies or rights from you under this License. If your rights have 
been terminated and not permanently reinstated, receipt of a copy of some or all of the 
same material does not give you any rights to use it. 


FUTURE REVISIONS OF THIS LICENSE 


The Free Software Foundation may publish new, revised versions of the GNU Free 
Documentation License from time to time. Such new versions will be similar in spirit 
to the present version, but may differ in detail to address new problems or concerns. 
See https: //www.gnu.org/licenses/. 


Each version of the License is given a distinguishing version number. If the Document 
specifies that a particular numbered version of this License “or any later version” 
applies to it, you have the option of following the terms and conditions either of that 
specified version or of any later version that has been published (not as a draft) by 
the Free Software Foundation. If the Document does not specify a version number of 
this License, you may choose any version ever published (not as a draft) by the Free 
Software Foundation. If the Document specifies that a proxy can decide which future 
versions of this License can be used, that proxy’s public statement of acceptance of a 
version permanently authorizes you to choose that version for the Document. 


RELICENSING 


“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide 
Web server that publishes copyrightable works and also provides prominent facilities 
for anybody to edit those works. A public wiki that anybody can edit is an example of 
such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the 
site means any set of copyrightable works thus published on the MMC site. 


“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license pub- 
lished by Creative Commons Corporation, a not-for-profit corporation with a principal 
place of business in San Francisco, California, as well as future copyleft versions of that 
license published by that same organization. 

“Incorporate” means to publish or republish a Document, in whole or in part, as part 
of another Document. 

An MMC is “eligible for relicensing” if it is licensed under this License, and if all works 
that were first published under this License somewhere other than this MMC, and 
subsequently incorporated in whole or in part into the MMC, (1) had no cover texts 
or invariant sections, and (2) were thus incorporated prior to November 1, 2008. 

The operator of an MMC Site may republish an MMC contained in the site under 
CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is 
eligible for relicensing. 
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Appendix E - Summary of Document Changes 


GnuCOBOL is an ever-evolving tool. While all reasonable attempts will be made to main- 
tain the currency of the information in this document, neither the author of this document 
nor the authors of the GnuCOBOL software extend any warranties of any kind for this 
document or for the information contained therein. 


1. 


8th Edition on release of v3.2 with some updates for 4.0+. 
2021. 
25/01 Updated version to v3.1.2 with date 25 Jan 21. 


29/01 Updated formats for OCCURS and now only using one file. Ditto for Quick 
Reference. 


7/02 Added procedure statement EXHIBIT, updated reserved words in Appendix C 
and removed same in Appendix B. 


4. 4/03 Modified Exhibit points 1/2 to loose the blank lines. 
5. 12/04 Updated text for CBL_SET_CSR_POS, repos EXHIBIT to 15B. 
6. 13/05 Updated USAGE for BINARY=C-LONG. Updated version to v3.2 with date 13 


May 2021. 


7. 15/05 Updated EXHIBIT and renumbered paragraphs. 
8. 24/08 Added detail for ACCEPT DAY-OF-WEEK. Changed descriptive for Display 


15 


screen-data-name removing screen and adding position specs see bug #743 now cleared. 
30/08 Change Appendix F to separate sections F1 through F4 adding changes for v3.1.1 
and v4. Added updates.texi after E.texi for latest document updates. 

5/09 Added Intrinsic functions BIT-OF, BIT-TO-CHAR, HEX-OF, HEX-TO-CHAR 
as 8.1.105 thru 108.but needs resorting of # in 8.1. Updated definition for CSSLEEP. 


. 12.09 Multi typo’s in sections 2, 3.5, .14, 6.9.51, 8.1.64B (chgd 2 to V2, 12.2, spotted 


by Patrik - Thank you for the updates. 


17/10 Extra information regarding LINE SEQUENTIAL file processing in 2.1.8 which 
refers to 10.2.3.4 and 10.2.3.7. 


17/10 CDF PAGE directive changes to details. Likewise to the Quick Reference manual. 
21/11 DIVIDE statement minor changes (#786). 
23/11 DIVIDE changed as 7.8.13.1 INTO and 13.3 BY, must have been asleep. 


25/11 Updated example listings in 10.1.1. updated to current default.conf in 10.1.5 as 
out of date. 

23/12 Update to START verb to make KEY compulsory for ISAM. 

24/12 Update to START added missing sub clauses [WITH SIZE] | [WITH LENGTH]. 
25/12 Update to sections 10.2.2 and 10.2.3 to clarify where program modules are loaded 
from i.e., directories pointed to by COB_LIBRARY-PATH and only if not found in 
PATH. Update to syntax diagran for START to clarify that SIZE and LENGTH key- 


words are mandatory words even if obvious. Updated description for COMBINED- 
DATETIME 
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20. 


21. 
22. 
23. 


24. 


25. 


26. 


27. 


28. 


29. 


30. 


Sl. 


32. 


33. 


34. 


30. 


36. 
37. 
38. 
39. 
AO. 
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31/12 Update to section 6.8.1 change program names to Usage-Lengths and replace 
the source listing to be correct positioned on cc8 as well as giving o/p for 64bit Linux. 
Bug #799. 

2022. 

07/01 Remove references to PATH in 10.2.2 &.3 wrong. 

16/01 In 2.2.5 near bottom example of compute 5 / 2.5 + 7 * 2- 1.15 had wrong result, 
should be 14.85. Clean up descriptions for USAGE COMP[UTATIONAL] & COMP 
etc in 6.9.49 and 7.8.1.2 accept from command-line. 

24/01 In 7.8.23 type fixed of elementary - remove ’3’ no vers change. 

17/02 In DISPLAY type 4 added OMITTED in place of identifier-1 to stop any screen 
content to change. 

07/03 IN 7.8.1.9, Accept EXCEPTION-STATUS these are two words i.e., EXCEP- 
TION STATUS not one. 


27/03 In 3.6 A comment included to advise that >>DEFINE should be used for new 
programs, over >>SET as it is not in the Cobol Standards. Included in 10.1 -Wno- 
terminator to stop warnings when not using END-XXX (Also see -Wterminator). 


07/04 IN section 3 CDF commands I have changed starting point from CC8 to cc7 as 
highlighted by Chris Gabel. 

21/04 In section 8.1 updated BYTE-LENGTH amd LENGTH-AN where referencing 
16 bit characters to use N(4) instead of X(4). 

23/04 In section 11.6.1.1, for Definitions of ’By Reference’ and ’By Content’ added 
missing ’by’. Spotted by Michael F Gleason, bug 828. 


03/05 In 8.1.82 & 83 for SUBSTITUTE and SUBSTITUE-CASE text on usage of 
variables, the need to use function TRIM is needed to remove leading and trailing 
spaces must be considered with example code block. 


15/05 In section 7.8.48 TRANSFORM added ’CHARACTERS’ to the format it has no 
effect with or without. 


1/06 In section 5.1.3 Show example of REPOSITORY has only the last entry with a 
period. In keeping with SPECIAL-NAMES etc that only the last entry has the period 
/ full stop terminator. Use extra space in 6.9.49 to show that the TO value in the 
FROM / TO values is NOT negative as only the From value is usually is. 


26/06 In 2.2.4 (+) should have been (-). Added Type (format 1) TYPEDEF, SAME 
AS in 6.9 and shifted down section numbers. 


29/06 Minor corrections to text for TYPEDEF, SAME AS & missing page reference. 
USAGE text addition. 


1/07 Adding XDF chapter 13. Early days - needs tidying up. 

6/07 In 6.9.53 added WHEN SET TO FALSE sub-clause in SYN-DD-VALUE-1. 
9/07 In 6.9.49 typo date should be data. 

10/07 Added functions CONCAT, CONTENT-LENGTH and CONTENT-OF. 
11/07 Adjusted and sorted functions at 8.1. 
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Al. 


42. 
43. 
AA. 


45. 


A6. 


AZ. 


A8. 


AQ. 


50. 
51. 


52. 


53. 
54. 


55. 


12/07 In 2.1.2 added details regardingsize of a user defined word i.e., from 31 chars 
to 63 using the right -std. In 7.8.17 EXIT statement RETURNING|GIVING missing 
from EXIT PROGRAM and description details. 


13/07 For ENTRY added missing GO TO and other content. 
16/07 For GO TO ENTRY entry-name added. 


27/08 Updated context for >>SOURCE in section 3.7 for FIXED, FREE, VARIABLE 
and others, likewise for >>SET. Updated copyright for FSF. 


05/09 Added new clauses in 6.9 - Data Description Clauses for PG and QR. 


11/09 Added PICTURE option 1 bit or boolean in 6.9.33 with a warning about compiler 
version implementation from v3.1l-rcl. In 6.9.46 last sentence changed ’four’ to ’eight’ 
for a double word binary number. 


26/09 Added Standard 85 EXAMINE verb at 7.8.15B. 


29/09 Added extra notes for CODE-SET referring to compiler version and the NEWS 
file. 


06/12 At 8.2.44 for offset addition to "The first byte of a file is byte offset 0" is "and 
MUST be preset to zero for first use". 

2023. 

02/01 At 7.8.1.5 Added ACCEPT from MICROSECOND-TIME (ACU. New commit 
[r4908] by sf-mensch. 


03/01 At 7.8.1.5 added more information regarding TIME and MICROSECONDS- 
TIME and update for FORMATTED-CURRENT-DATE in 8.1.29. 


04/01 7.8.1.5 Diagram had missing TIME and text had 2 copies of it. 


06/01 6.8.1 01-Level Constants, added arithmetic-espression-1. Re-introduced Updates 
from ed. 8. 


15/01 8.1.33 FRACTION-PART Included text to specify picture must include preced- 
ing ’V’ and provide better example. 
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